doc/htex/ug14.htex

% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% 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.

% *********************************************************************
\head{chapter}{Browse}{ugBrowse}
% *********************************************************************

This chapter discusses the \Browse{}
\index{Browse@\Browse{}}
component of \HyperName{}.
\index{HyperDoc@{\HyperName{}}}
We suggest you invoke \Language{} and work through this
chapter, section by section, following our examples to gain some
familiarity with \Browse{}.

% *********************************************************************
\head{section}{The Front Page: Searching the Library}{ugBrowseStart}
% *********************************************************************
To enter \Browse{}, click on {\bf Browse} on the top level page
of \HyperName{} to get the {\it front page} of \Browse{}.
%
%324pt is 4.5",180pt is 2.5",432pt is 6"=textwidth,54=(432-324)/2
%ps files are 4.5"x2.5" except source 4.5"x2.5"
%
\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-brfront.ps}
\end{picture}
\caption{The Browse front page.}
\end{figure}
\end{texonly}

To use this page, you first enter a \spadgloss{search string} into
the input area at the top, then click on one of the buttons below.
We show the use of each of the buttons by example.

\subsubsection{Constructors}

First enter the search string {\tt Matrix} into the input area and
click on {\bf Constructors}.
What you get is the {\it constructor page} for \spadtype{Matrix}.
We show and describe this page in detail in
\spadref{ugBrowseDomain}.
By convention, \Language{} does a case-insensitive search for a
match.
Thus {\tt matrix} is just as good as {\tt Matrix}, has the same
effect as {\tt MaTrix}, and so on.
We recommend that you generally use small letters for names
however.
A search string with only capital letters has a special meaning
(see \spadref{ugBrowseCapitalizationConvention}).


Click on \UpBitmap{} to return to the \Browse{} front page.

Use the symbol ``{\tt *}'' in search strings as a \spadgloss{wild
card}.
A wild card matches any substring, including the empty string.
For example, enter the search string {\tt *matrix*} into the input
area and click on {\bf Constructors}.\footnote{To get only
categories, domains, or packages, rather than all constructors,
you can click on the corresponding button to the right of {\bf
Constructors}.}
What you get is a table of all constructors whose names contain
the string ``{\tt matrix}.''

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-consearch.ps}
\end{picture}
\caption{Table of exposed constructors matching \texttt{*matrix*}.}
\end{figure}
\end{texonly}

%% Following para replaced 1995oct30 MGR
%These are all the \spadglossSee{exposed}{expose} constructors in
%\Language{}.
%To see how to get all exposed and unexposed constructors in
%\Language{}, skip to the section entitled {\bf Exposure} in
%\spadref{ugBrowseOptions}.
All constructors containing the string are listed, whether
\spadglossSee{exposed}{expose} or \spadglossSee{unexposed}{expose}.
You can hide the names of the unexposed constructors by clicking
on the {\it *=}{\bf unexposed} button in the {\it Views} panel at
the bottom of the window.
(The button will change to {\bf exposed} {\it only}.)

One of the names in this table is \spadtype{Matrix}.
Click on \spadtype{Matrix}.
What you get is again the constructor page for \spadtype{Matrix}.
As you see, \Browse{} gives you a large network of
information in which there are many ways to reach the same
pages.
\exptypeindex{Matrix}

Again click on the \UpBitmap{} to return to the table of constructors
whose names contain {\tt matrix}.
%Below the table is a {\bf Views} panel. % here & globally MGR 1995oct30
Below the table is a {\it Views} panel.
This panel contains buttons that let you view constructors in different
ways.
To learn about views of constructors, skip to
\spadref{ugBrowseViewsOfConstructors}.

Click on \UpBitmap{} to return to the \Browse{} front page.

\subsubsection{Operations}

Enter {\tt *matrix} into the input area and click on {\bf
Operations}.
This time you get a table of {\it operations} whose names end with {\tt
matrix} or {\tt Matrix}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matrixops.ps}
\end{picture}
\caption{Table of operations matching \texttt{*matrix}.}
\end{figure}
\end{texonly}

If you select an operation name, you go to a page describing all
the operations in \Language{} of that name.
At the bottom of an operation page is another kind of {\it Views} panel,
one for operation pages.
To learn more about these views, skip to
\spadref{ugBrowseViewsOfOperations}.

Click on \UpBitmap{} to return to the \Browse{} front page.

\subsubsection{General}

This button does a general search for all constructor and operation
names matching the search string.
Enter the search string \allowbreak
{\tt *matrix*} into the input area.
Click on {\bf General} to find all constructs that have {\tt
matrix} as a part of their name.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-gensearch.ps}
\end{picture}
\caption{Table of all constructs matching \texttt{*matrix*}.}
\end{figure}
\end{texonly}

The summary gives you all the names under a heading when the number of
entries is less than 10. % "less than 10." replaces the following:
                         % sufficiently small%\footnote{See
%\spadref{ugBrowseOptions} to see how you can change this.}.
%% MGR 1995oct31

Click on \UpBitmap{} to return to the \Browse{} front page.

\subsubsection{Documentation}

Again enter the search key {\tt *matrix*} and this time click on
{\bf Documentation}.
This search matches any constructor and operation
name whose documentation contains a substring matching {\tt
matrix}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-docsearch.ps}
\end{picture}
\caption{Table of constructs with documentation matching \texttt{*matrix*}.}
\end{figure}
\end{texonly}

Click on \UpBitmap{} to return to the \Browse{} front page.

\subsubsection{Complete}

This search combines both {\bf General} and {\bf Documentation}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-comsearch.ps}
\end{picture}
\caption{Table summarizing complete search for pattern \texttt{*matrix*}.}
\end{figure}
\end{texonly}

% *********************************************************************
\head{section}{The Constructor Page}{ugBrowseDomain}
% *********************************************************************

In this section we look in detail at a constructor page for domain
\spadtype{Matrix}.
Enter {\tt matrix} into the input area on the main \Browse{} page
and click on {\bf Constructors}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matpage.ps}
\end{picture}
\caption{Constructor page for \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}


The header part tells you that \spadtype{Matrix} has abbreviation
\spadtype{MATRIX} and one argument called {\tt R} that must be a
domain of category \spadtype{Ring}.
Just what domains can be arguments of \spadtype{Matrix}?
To find this out, click on the {\tt R} on the second line of the
heading.
What you get is a table of all acceptable domain parameter values
of {\tt R}, or a table of \spadgloss{rings} in \Language{}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matargs.ps}
\end{picture}
\caption{Table of acceptable domain parameters to \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

Click on \UpBitmap{} to return to the constructor page for
\spadtype{Matrix}.
\texht{\newpage}{}

If you have access to the source code of \Language{}, the third
\index{source code}
line of the heading gives you the name of the source file
containing the definition of \spadtype{Matrix}.
Click on it to pop up an editor window containing the source code
of \spadtype{Matrix}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,168)%(-54,0)
\special{psfile=h-matsource.ps}
\end{picture}
\caption{Source code for \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

We recommend that you leave the editor window up while working
through this chapter as you occasionally may want to refer to it.
\texht{\newpage}{}

% *********************************************************************
\head{subsection}{Constructor Page Buttons}{ugBrowseDomainButtons}
% *********************************************************************

We examine each button on this page in order.

\subsubsection{Description}

Click here to bring up a page with a brief description of
constructor \spadtype{Matrix}.
If you have access to system source code, note that these comments
can be found directly over the constructor definition.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matdesc.ps}
\end{picture}
\caption{Description page for \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

\subsubsection{Operations}

Click here to get a table of operations exported by
\spadtype{Matrix}.
You may wish to widen the window to have multiple columns as
below.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matops.ps}
\end{picture}
\caption{Table of operations from \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

If you click on an operation name, you bring up a description
page for the operations.
For a detailed description of these pages, skip to
\spadref{ugBrowseViewsOfOperations}.

\subsubsection{Examples}

Click here to get an {\it examples page} with examples of operations to
create and manipulate matrices.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matexamp.ps}
\end{picture}
\caption{Example page for \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

Read through this section.
Try selecting the various buttons.
Notice that if you click on an operation name, such as
\spadfunFrom{new}{Matrix}, you bring up a description page for that
operation from \spadtype{Matrix}.

Example pages have several examples of \Language{} commands.
Each example has an active button to its left.
Click on it!
A pre-computed answer is pasted into the page immediately following the
command.
If you click on the button a second time, the answer disappears.
This button thus acts as a toggle:
``now you see it; now you don't.''

Note also that the \Language{} commands themselves are active.
If you want to see \Language{} execute the command, then click on it!
A new \Language{} window appears on your screen and the command is
executed.

\begin{htonly}
At the end of the page is generally a menu of buttons that lead
you to further sections.
Select one of these topics to explore its contents.
\end{htonly}

\subsubsection{Exports}

Click here to see a page describing the exports of \spadtype{Matrix}
exactly as described by the source code.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matexports.ps}
\end{picture}
\caption{Exports of \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

As you see, \spadtype{Matrix} declares that it exports all the operations
and categories exported by category
\spadtype{MatrixCategory(R, Row, Col)}.
In addition, two operations, \spadfun{diagonalMatrix} and
\spadfun{inverse}, are explicitly exported.

To learn a little about the structure of \Language{}, we suggest you do
the following exercise.
\begin{texonly}
Otherwise, go on to the next section.
\end{texonly}
\begin{htonly}
Otherwise, click on \UpButton{} and go on to the next section.
\end{htonly}
\spadtype{Matrix} explicitly exports only two operations.
The other operations are thus exports of \spadtype{MatrixCategory}.
In general, operations are usually not explicitly exported by a domain.
Typically they are \spadglossSee{inherited}{inherit} from several
different categories.
Let's find out from where the operations of \spadtype{Matrix} come.

\begin{enumerate}
\item Click on {\bf MatrixCategory}, then on {\bf Exports}.
Here you see that {\bf MatrixCategory} explicitly exports many matrix
operations.
Also, it inherits its operations from
\spadtype{TwoDimensionalArrayCategory}.

\item Click on {\bf TwoDimensionalArrayCategory}, then on {\bf Exports}.
Here you see explicit operations dealing with rows and columns.
In addition, it inherits operations from
\spadtype{HomogeneousAggregate}.

%\item Click on {\bf HomogeneousAggregate}, then on {\bf Exports}.
%And so on.
%If you continue doing this, eventually you will

\item Click on \UpBitmap{} and then
click on {\bf Object}, then on {\bf Exports}, where you see
there are no exports.

\item Click on \UpBitmap{} repeatedly to return to the constructor page
for \spadtype{Matrix}.

\end{enumerate}

\subsubsection{Related Operations}

Click here bringing up a table of operations that are exported by
\spadglossSee{packages}{package} but not by \spadtype{Matrix} itself.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matrelops.ps}
\end{picture}
\caption{Related operations of \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

To see a table of such packages, use the {\bf Relatives} button on the
{\bf Cross Reference} page described next.


% *********************************************************************
\head{subsection}{Cross Reference}{ugBrowseCrossReference}
% *********************************************************************
Click on the {\bf Cross Reference} button on the main constructor page
for \spadtype{Matrix}.
This gives you a page having various cross reference information stored
under the respective buttons.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matxref.ps}
\end{picture}
\caption{Cross-reference page for \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

\subsubsection{Parents}

The parents of a domain are the same as the categories mentioned under
the {\bf Exports} button on the first page.
Domain \spadtype{Matrix} has only one parent but in general a domain can
have any number.

\subsubsection{Ancestors}

The \spadglossSee{ancestors}{ancestor} of a constructor consist of its parents, the
parents of its parents, and so on.
Did you perform the exercise in the last section under {\bf Exports}?
If so, you  see here all the categories you found while ascending the
{\bf Exports} chain for \spadtype{Matrix}.

\subsubsection{Relatives}

The \spadglossSee{relatives}{relative} of a domain constructor are package
constructors that provide operations in addition to those
\spadglossSee{exported}{export} by the domain.

Try this exercise.
\begin{enumerate}
\item Click on {\bf Relatives}, bringing up a list of
\spadglossSee{packages}{package}.

\item Click on {\bf LinearSystemMatrixPackage} bringing up its
constructor page.\footnote{You may want to widen your \HyperName{}
window to make what follows more legible.}

\item Click on {\bf Operations}.
Here you see \spadfun{rank}, an operation also exported by
\spadtype{Matrix} itself.

\item Click on {\bf rank}.
This \spadfunFrom{rank}{LinearSystemMatrixPackage} has two arguments and
thus is different from the \spadfunFrom{rank}{Matrix} from
\spadtype{Matrix}.

\item Click on \UpBitmap{} to return to the list of operations for the
package \spadtype{LinearSystemMatrixPackage}.

\item Click on {\bf solve} to bring up a
\spadfunFrom{solve}{LinearSystemMatrixPackage} for linear systems of
equations.

\item Click on \UpBitmap{} several times to return to the cross
reference page for \spadtype{Matrix}.
\end{enumerate}

\subsubsection{Dependents}

The \spadglossSee{dependents}{dependent} of a constructor are those
\spadglossSee{domains}{domain} or \spadglossSee{packages}{package}
that mention that
constructor either as an argument or in its \spadglossSee{exports}{export}.

If you click on {\bf Dependents} two entries may surprise you:
\spadtype{RectangularMatrix} and \spadtype{SquareMatrix}.
This happens because \spadtype{Matrix}, as it turns out, appears in
signatures of operations exported by these domains.

\subsubsection{Search Path}

The term \spadgloss{search path} refers to the {\it search order} for
functions.
If you are an expert user or curious about how the \Language{} system
works, try the following exercise.
Otherwise, you best skip this button and go on to {\bf Users}.

Clicking on {\bf Search Path} gives you a
list of domain constructors:
\spadtype{InnerIndexedTwoDimensionalArray},
\aliascon{MatrixCategory&}{MATCAT-},
\aliascon{TwoDimensionalArrayCategory&}{ARR2CAT-},
\aliascon{HomogeneousAggregate&}{HOAGG-},
\aliascon{Aggregate&}{AGG-},
\aliascon{Evalable&}{EVALAB-},
\aliascon{SetCategory&}{SETCAT-},
\aliascon{InnerEvalable&}{IEVALAB-},
\aliascon{BasicType&}{BASTYPE-}.
What are these constructors and how are they used?

We explain by an example.
Suppose you create a matrix using the interpreter, then ask for its
\spadfun{rank}.
\Language{} must then find a function implementing the \spadfun{rank}
operation for matrices.
The first place \Language{} looks for \spadfun{rank} is in the \spadtype{Matrix}
domain.

If not there, the search path of \spadtype{Matrix} tells \Language{} where
else to look.
Associated with the matrix domain are eight other search path domains.
Their order is important.
\Language{} first searches the first one,
\spadtype{InnerIndexedTwoDimensionalArray}.
If not there, it searches the second \aliascon{MatrixCategory&}{MATCAT-}.
And so on.

Where do these {\it search path constructors} come from?
The source code for \spadtype{Matrix} contains this syntax for the
\spadgloss{function body} of
\spadtype{Matrix}:\footnote{\spadtype{InnerIndexedTwoDimensionalArray}
is a special domain implemented for matrix-like domains to provide
efficient implementations of \twodim{} arrays.
For example, domains of category \spadtype{TwoDimensionalArrayCategory}
can have any integer as their \spad{minIndex}.
Matrices and other members of this special ``inner'' array have their
\spad{minIndex} defined as \spad{1}.}
\begin{verbatim}
InnerIndexedTwoDimensionalArray(R,mnRow,mnCol,Row,Col)
   add ...
\end{verbatim}
where the ``{\tt ...}'' denotes all the code that follows.
In English, this means:
``The functions for matrices are defined as those from
\spadtype{InnerIndexedTwoDimensionalArray} domain augmented by those
defined in `{\tt ...}','' where the latter take precedence.

This explains \spadtype{InnerIndexedTwoDimensionalArray}.
The other names, those with names ending with an ampersand \spadSyntax{&} are
\spadglossSee{default packages}{default package}
for categories to which \spadtype{Matrix} belongs.
Default packages are ordered by the notion of ``closest ancestor.''

\subsubsection{Users}

A user of \spadtype{Matrix} is any constructor that uses
\spadtype{Matrix} in its implementation.
For example, \spadtype{Complex} is a user of \spadtype{Matrix}; it
exports several operations that take matrices as arguments or return
matrices as values.\footnote{A constructor is a user of
\spadtype{Matrix} if it handles any matrix.
For example, a constructor having internal (unexported) operations
dealing with matrices is also a user.}

\subsubsection{Uses}

A \spadgloss{benefactor} of \spadtype{Matrix} is any constructor that
\spadtype{Matrix} uses in its implementation.
This information, like that for clients, is gathered from run-time
structures.\footnote{The benefactors exclude constructors such as
\spadtype{PrimitiveArray} whose operations macro-expand and so vanish
from sight!}

Cross reference pages for categories have some different buttons on
them.
Starting with the constructor page of \spadtype{Matrix}, click on
\spadtype{Ring} producing its constructor page.
Click on {\bf Cross Reference},
producing the cross-reference page for \spadtype{Ring}.
Here are buttons {\bf Parents} and {\bf Ancestors} similar to the notion
for domains, except for categories the relationship between parent and
child is defined through \spadgloss{category extension}.

\subsubsection{Children}

Category hierarchies go both ways.
There are children as well as parents.
A child can have any number of parents, but always at least one.
Every category is therefore a descendant of exactly one category:
\spadtype{Object}.

\subsubsection{Descendants}

These are children, children of children, and so on.

Category hierarchies are complicated by the fact that categories take
parameters.
Where a parameterized category fits into a hierarchy {\it may} depend on
values of its parameters.
In general, the set of categories in \Language{} forms a {\it directed
acyclic graph}, that is, a graph with directed arcs and no cycles.

\subsubsection{Domains}

This produces a table of all domain constructors that can possibly be
rings (members of category \spadtype{Ring}).
Some domains are unconditional rings.
Others are rings for some parameters and not for others.
To find out which, select the {\bf conditions} button in the views
panel.
For example, \spadtype{DirectProduct(n, R)} is a ring if {\tt R} is a
ring.


% *********************************************************************
\head{subsection}{Views Of Constructors}{ugBrowseViewsOfConstructors}
% *********************************************************************

Below every constructor table page is a {\it Views} panel.
As an example, click on {\bf Cross Reference} from
the constructor page of \spadtype{Matrix},
then on {\bf Benefactors} to produce a
short table of constructor names.

The {\it Views} panel is at the bottom of the page.
Two items, {\it names} and {\it conditions,} are in italics.
Others are active buttons.
The active buttons are those that give you useful alternative views
on this table of constructors.
Once you select a view, you notice that the button turns
off (becomes italicized) so that you cannot reselect it.

\subsubsection{names}

This view gives you a table of names.
Selecting any of these names brings up the constructor page for that
constructor.

\subsubsection{abbrs}

This view gives you a table of abbreviations, in the same order as the
original constructor names.
Abbreviations are in capitals and are limited to 7 characters.
They can be used interchangeably with constructor names in input areas.

\subsubsection{kinds}

This view organizes constructor names into
the three kinds: categories, domains and packages.

\subsubsection{files}

This view gives a table of file names for the source
code of the constructors in alphabetic order after removing
duplicates.

\subsubsection{parameters}

This view presents constructors with the arguments.
This view of the benefactors of \spadtype{Matrix} shows that
\spadtype{Matrix} uses as many as five different \spadtype{List} domains
in its implementation.

\subsubsection{filter}

This button is used to refine the list of names or abbreviations.
Starting with the {\it names} view, enter {\tt m*} into the input area
and click on {\bf filter}.
You then get a shorter table with only the names beginning with {\tt m}.

\subsubsection{documentation}

This gives you documentation for each of the constructors.

\subsubsection{conditions}

This page organizes the constructors according to predicates.
The view is not available for your example page since all constructors
are unconditional.
For a table with conditions, return to the {\bf Cross Reference} page
for \spadtype{Matrix}, click on {\bf Ancestors}, then on {\bf
conditions} in the view panel.
This page shows you that \spadtype{CoercibleTo(OutputForm)} and
\spadtype{SetCategory} are ancestors of \spadtype{Matrix(R)} only if {\tt R}
belongs to category \spadtype{SetCategory}.

%*********************************************************************
\head{subsection}{Giving Parameters to Constructors}{ugBrowseGivingParameters}
%*********************************************************************

Notice the input area at the bottom of the constructor page.
If you leave this blank, then the information you get is for the
domain constructor \spadtype{Matrix(R)}, that is, \spadtype{Matrix} for an
arbitrary underlying domain {\tt R}.

In general, however, the exports and other information {\it do} usually
depend on the actual value of {\tt R}.
For example, \spadtype{Matrix} exports the \spadfun{inverse} operation
only if the domain {\tt R} is a \spadtype{Field}.
To see this, try this from the main constructor page:

\begin{enumerate}
\item Enter {\tt Integer} into the input area at the bottom of the page.

\item Click on {\bf Operations}, producing a table of operations.
Note the number of operation names that appear at the top of the
page.

\item Click on \UpBitmap{} to return to the constructor page.

\item Use the
\texht{\fbox{\bf Delete}}{{\bf Delete}}
or
\texht{\fbox{\bf Backspace}}{{\bf Backspace}}
keys to erase {\tt Integer} from the input area.

\item Click on {\bf Operations} to produce a new table of operations.
Look at the number of operations you get.
This number is greater than what you had before.
Find, for example, the operation \spadfun{inverse}.

\item Click on {\bf inverse} to produce a page describing the operation
\spadfun{inverse}.
At the bottom of the description, you notice that the {\bf
Conditions} line says ``{\tt R} has \spadtype{Field}.''
This operation is {\it not} exported by \spadtype{Matrix(Integer)} since
\spadtype{Integer} is not a \spadgloss{field}.

Try putting the name of a domain such as \spadtype{Fraction Integer}
(which is a field) into the input area, then clicking on {\bf Operations}.
As you see, the operation \spadfun{inverse} is exported.
\end{enumerate}

% *********************************************************************
\head{section}{Miscellaneous Features of Browse}{ugBrowseMiscellaneousFeatures}
% *********************************************************************
% *********************************************************************
\head{subsection}{The Description Page for Operations}{ugBrowseDescriptionPage}
% *********************************************************************
From the constructor page of \spadtype{Matrix},
click on {\bf Operations} to bring up the table of operations
for \spadtype{Matrix}.

Find the operation {\bf inverse} in the table and click on it.
This takes you to a page showing the documentation for this operation.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matinv.ps}
\end{picture}
\caption{Operation \protect\spadfunFrom{inverse}{Matrix} from \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

Here is the significance of the headings you see.

\subsubsection{Arguments}

This lists each of the arguments of the operation in turn, paraphrasing
the \spadgloss{signature} of the operation.
As for signatures, a \spadSyntax{%} is used to designate {\em this domain},
that is, \spadtype{Matrix(R)}.

\subsubsection{Returns}

This describes the return value for the operation, analogous to the {\bf
Arguments} part.

\subsubsection{Origin}

This tells you which domain or category explicitly exports the
operation.
In this example, the domain itself is the {\it Origin}.


\subsubsection{Conditions}

This tells you that the operation is exported by \spadtype{Matrix(R)} only if
``{\tt R} has \spadtype{Field},'' that is, ``{\tt R} is a member of
category \spadtype{Field}.''
When no {\bf Conditions} part is given, the operation is exported for
all values of {\tt R}.

\subsubsection{Description}

Here are the \spadSyntax{++} comments
that appear in the source code of its {\it Origin}, here \spadtype{Matrix}.
You find these comments in the source code for \spadtype{Matrix}.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matmap.ps}
\end{picture}
\caption{Operations \protect\spadfun{map} from \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

Click on \UpBitmap{} to return to the table of operations.
Click on {\bf map}.
Here you find three different operations named \spadfun{map}.
This should not surprise you.
Operations are identified by name and \spadgloss{signature}.
There are three operations named \spadfun{map}, each with
different signatures.
What you see is the {\it descriptions} view of the operations.
If you like, select the button in the heading of one of these
descriptions to get {\it only} that operation.

\subsubsection{Where}

This part qualifies domain parameters mentioned in the arguments to the
operation.

% *********************************************************************
\head{subsection}{Views of Operations}{ugBrowseViewsOfOperations}
% *********************************************************************

We suggest that you go to the constructor page for \spadtype{Matrix}
and click on {\bf Operations} to bring up a table of operations
with a {\it Views} panel at the bottom.

\subsubsection{names}

This view lists the names of the operations.
Unlike constructors, however, there may be several operations with the
same name.
The heading for the page tells you the number of unique names and the
number of distinct operations when these numbers are different.

\subsubsection{filter}

As for constructors, you can use this button to cut down the list of
operations you are looking at.
Enter, for example, {\tt m*} into the input area to the right of {\bf
filter} then click on {\bf filter}.
As usual, any logical expression is permitted.
For example, use
\begin{verbatim}
*! or *?
\end{verbatim}
to get a list of destructive operations and predicates.

\subsubsection{documentation}

This gives you the most information:
a detailed description of all the operations in the form you have seen
before.
Every other button summarizes these operations in some form.

\subsubsection{signatures}

This views the operations by showing their signatures.

\subsubsection{parameters}

This views the operations by their distinct syntactic forms with
parameters.

\subsubsection{origins}

This organizes the operations according to the constructor that
explicitly exports them.

\subsubsection{conditions}

This view organizes the operations into conditional and unconditional
operations.

\subsubsection{usage}

This button is only available if your user-level is set to {\it
\index{user-level}
development}.
The {\bf usage} button produces a table of constructors that reference this
operation.\footnote{\Language{} requires an especially long time to
produce this table, so anticipate this when requesting this
information.}

\subsubsection{implementation}

This button is only available if your user-level is set to {\it
development}.
\index{user-level}
If you enter values for all domain parameters on the constructor page,
then the {\bf implementation} button appears in place of the {\bf
conditions} button.
This button tells you what domains or packages actually implement the
various operations.\footnote{This button often takes a long time; expect
a delay while you wait for an answer.}

With your user-level set to {\it development}, we suggest you try this
exercise.
Return to the main constructor page for \spadtype{Matrix}, then enter
{\tt Integer} into the input area at the bottom as the value of {\tt R}.
Then click on {\bf Operations} to produce a table of operations.
Note that the {\bf conditions} part of the {\it Views} table is
replaced by {\bf implementation}.
Click on {\bf implementation}.
After some delay, you get a page describing what implements each of
the matrix operations, organized by the various domains and packages.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-matimp.ps}
\end{picture}
\caption{Implementation domains for \protect\spadtype{Matrix}.}
\end{figure}
\end{texonly}

\subsubsection{generalize}

This button only appears for an operation page of a constructor
involving a unique operation name.

From an operations page for \spadtype{Matrix}, select any
operation name, say {\bf rank}.
In the views panel, the {\bf filter} button is  replaced by
{\bf generalize}.
Click on it!
%% Replaced {\bf threshold} with 10 below.  MGR 1995oct31
What you get is a description of all \Language{} operations
named \spadfun{rank}.\footnote{If there were more than 10
operations of the name, you get instead a page
with a {\it Views} panel at the bottom and the message to {\bf
Select a view below}.
To get the descriptions of all these operations as mentioned
above, select the {\bf description} button.}
%See the discussion of {\bf threshold} in
%\spadref{ugBrowseOptions}.} %% Removed MGR 1995oct31

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-allrank.ps}
\end{picture}
\caption{All operations named \protect\spadfun{rank} in \Language{}.}
\end{figure}
\end{texonly}

\subsubsection{all domains}

This button only appears on an operation page resulting from a
search from the front page of \Browse{} or from selecting
{\bf generalize} from an operation page for a constructor.

Note that the {\bf filter} button in the {\it Views} panel is
replaced by {\bf all domains}.
Click on it to produce a table of {\it all} domains or packages that
export a \spadfun{rank} operation.

\begin{texonly}
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=h-alldoms.ps}
\end{picture}
\caption{Table of all domains that export \spadfun{rank}.}
\end{figure}
\end{texonly}

We note that this table specifically refers to all the \spadfun{rank}
operations shown in the preceding page.
Return to the descriptions of all the \spadfun{rank} operations and
select one of them by clicking on the button in its heading.
Select {\bf all domains}.
As you see, you have a smaller table of constructors.
When there is only one constructor, you get the
constructor page for that constructor.
\texht{\newpage}{}

% *********************************************************************
\head{subsection}{Capitalization Convention}{ugBrowseCapitalizationConvention}
% *********************************************************************

When entering search keys for constructors, you can use capital
letters to search for abbreviations.
For example, enter {\tt UTS} into the input area and click on {\bf
Constructors}.
Up comes a page describing \spadtype{UnivariateTaylorSeries}
whose abbreviation is \spadtype{UTS}.

Constructor abbreviations always have three or more capital
letters.
For short constructor names (six letters or less), abbreviations
are not generally helpful as their abbreviation is typically the
constructor name in capitals.
For example, the abbreviation for \spadtype{Matrix} is
\spadtype{MATRIX}.

Abbreviations can also contain numbers.
For example, \spadtype{POLY2} is the abbreviation for constructor
\spadtype{PolynomialFunctions2}.
For default packages, the abbreviation is the same as the
abbreviation for the corresponding category with the ``\&''
replaced by ``-''.
For example, for the category default package
\aliascon{MatrixCategory&}{MATCAT-} the abbreviation is
\spadtype{MATCAT-} since the corresponding category
\spadtype{MatrixCategory} has abbreviation \spadtype{MATCAT}.

%% *********************************************************************
%\head{subsection}{Browse Options}{ugBrowseOptions}
%% *********************************************************************
%
%You can set two options for using \Browse{}: exposure and threshold.
%
%% *********************************************************************
%\subsubsection{Exposure}
%% *********************************************************************
%
%By default, the only constructors and operations
%shown by \Browse{} are those from \spadglossSee{exposed constructors}{expose}.
%To change this, you can issue
%\syscmdindex{set hyperdoc browse exposure}
%\begin{verbatim}
%)set hyperdoc browse exposure on
%\end{verbatim}
%After you make this setting, you will see
%both exposed and unexposed constructs.
%By definition, an operation is exposed only if it is
%exported from an exposed constructor.
%Unexposed items are generally marked by \Browse{} with an asterisk.
%For more information on exposure, see \spadref{ugTypesExpose}.
%
%With this setting, try the following experiment.
%Starting with the main \Browse{} page, enter {\tt *matrix*} into the
%input area and click on {\bf Constructors}.
%The result is the following table. %% This line  should be texonly. MGR
%
%\begin{texonly}
%\begin{figure}[htbp]
%\begin{picture}(324,180)%(-54,0)
%\hspace*{\baseLeftSkip}\special{psfile=h-consearch2.ps}
%\end{picture}
%\caption{Table of all constructors matching {\tt *matrix*} .}
%\end{figure}
%\end{texonly}
%
%
%% *********************************************************************
%\subsubsection{Threshold}
%% *********************************************************************
%
%For General, Documentation or Complete searches, a summary is presented
%of all matches.
%When the number of items of a given kind is less than a number called
%{\bf threshold}, \Language{} presents a table of names with the heading
%for that kind.
%
%Also, when an operation name is chosen and there are less than {\bf
%threshold} distinct operations, the operations are initially shown in
%{\bf description} mode.
%
%The default value of {\bf threshold} is 10.
%To change its value to say 5, issue
%\syscmdindex{set hyperdoc browse threshold}
%\begin{verbatim}
%)set hyperdoc browse threshold 5
%\end{verbatim}
%Notice that the headings in
%the summary are active.
%If you click on a heading, you bring up a separate page for those
%entries.
%%
%% Above section removed by MGR, 1995oct30, as these two options do
%% not exist.