
% 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}{Using \HyperName{}}{ugHyper}
% *********************************************************************

\includehyperdoc{h-root}{The \HyperName{} root window page.}

\HyperName{} is the gateway to \Language{}.
\index{HyperDoc @{\protect\HyperName{}}}
It's both an on-line tutorial and an on-line reference manual.
It also enables you to use \Language{} simply by using the mouse and
filling in templates.
\HyperName{} is available to you if you are running \Language{} 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.}

\begin{htonly}
We suggest that you learn more about other features of
\HyperName{} by clicking on an active area in the menu below.
\end{htonly}

% *********************************************************************
\head{section}{Headings}{ugHyperHeadings}
% *********************************************************************
%
Most pages have a standard set of buttons at the top of the page.
These are what they mean:

\begin{description}
\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.
\end{description}
%
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.

% *********************************************************************
\head{section}{Key Definitions}{ugHyperKeys}
% *********************************************************************

The following keyboard definitions are in effect throughout
\HyperName{}.
See \spadref{ugHyperScroll} and
\spadref{ugHyperInput}
for some contextual key definitions.
%
\begin{description}
\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.
\end{description}

% *********************************************************************
\head{section}{Scroll Bars}{ugHyperScroll}
% *********************************************************************
%

Whenever there is too much text to fit on a page, a {\it scroll
\index{scroll bar}
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 \spadref{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.

% *********************************************************************
\head{section}{Input Areas}{ugHyperInput}
% *********************************************************************
%
Input areas are boxes where you can put data.
\begin{htonly}
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 _}).
\end{htonly}

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 a page, 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.

% *********************************************************************
\head{section}{Radio Buttons and Toggles}{ugHyperButtons}
% *********************************************************************
%
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.
\begin{htonly}
\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
\end{htonly}
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.
\begin{htonly}
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
\end{htonly}
To change toggle the selection, move the cursor with the mouse
to the button and click.

% *********************************************************************
\head{section}{Search Strings}{ugHyperSearch}
% *********************************************************************
%
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{}:
\begin{enumerate}
\item Click on \windowlink{Reference}{TopReferencePage},
bringing up the \Language{} Reference page.
\item Click on \windowlink{Glossary}{GlossaryPage}, bringing up the glossary.
\end{enumerate}
\begin{htonly}
Once you get the window containing the glossary, move it so that
it and this window are both visible.
\end{htonly}

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 can 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.

% *********************************************************************
\head{subsection}{Logical Searches}{ugLogicalSearches}
% *********************************************************************

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 \Language{} 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,
\begin{center}
{\tt a* or b* or c* or d* or e* and (not *a*)}
\end{center}
is a valid expression.

% *********************************************************************
\head{section}{Example Pages}{ugHyperExample}
% *********************************************************************
%
Many pages have \Language{} example commands.
%
\begin{htonly}
Here are two:
\spadcommand{a:= x^2 + 1 \bound{a}}
\spadcommand{(a - 2)^2 \free{a}}
\end{htonly}
%
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
\Language{} 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!
\begin{htonly}
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?
\Language{} first issues the first line (to assign \spad{a}), then the
second (to do the computation using \spad{a}).
\end{htonly}

The new interactive \Language{} 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 \Language{} system command \spadsys{)close}.
\syscmdindex{close}

% *********************************************************************
\head{section}{X Window Resources for \HyperName{}}{ugHyperResources}
% *********************************************************************
%
You can control the appearance of \HyperName{} while running under Version 11
\index{HyperDoc @{\protect\HyperName{}}!X Window System defaults}
of the X Window System by placing the following resources
\index{X Window System}
in the file {\bf .Xdefaults} in your home directory.
\index{file!.Xdefaults @{\bf .Xdefaults}}
In what follows, {\it font} is any valid X11 font name
\index{font}
(for example, {\tt Rom14}) and {\it color} is any valid X11 color
\index{color}
specification (for example, {\tt NavyBlue}).
For more information about fonts and colors, refer to the
X Window documentation for your system.
\begin{description}
\item[{\tt FriCAS.hyperdoc.RmFont:} {\it font}] \ \newline
This is the standard text font.  \xdefault{Rom14}
\item[{\tt FriCAS.hyperdoc.RmColor:} {\it color}] \ \newline
This is the standard text color.  \xdefault{black}
\item[{\tt FriCAS.hyperdoc.ActiveFont:} {\it font}] \ \newline
This is the font used for \HyperName{} link buttons.  \xdefault{Bld14}
\item[{\tt FriCAS.hyperdoc.ActiveColor:} {\it color}] \ \newline
This is the color used for \HyperName{} link buttons.  \xdefault{black}
\item[{\tt FriCAS.hyperdoc.FriCASFont:} {\it font}] \ \newline
This is the font used for active \Language{} commands.
\xdefault{Bld14}
\item[{\tt FriCAS.hyperdoc.FriCASColor:} {\it color}] \ \newline
This is the color used for active \Language{} commands.
\xdefault{black}
\item[{\tt FriCAS.hyperdoc.BoldFont:} {\it font}] \ \newline
This is the font used for bold face.  \xdefault{Bld14}
\item[{\tt FriCAS.hyperdoc.BoldColor:} {\it color}] \ \newline
This is the color used for bold face.  \xdefault{black}
\item[{\tt FriCAS.hyperdoc.TtFont:} {\it font}] \ \newline
This is the font used for \Language{} output in \HyperName{}.
This font must be fixed-width.  \xdefault{Rom14}
\item[{\tt FriCAS.hyperdoc.TtColor:} {\it color}] \ \newline
This is the color used for \Language{} output in \HyperName{}.
\xdefault{black}
\item[{\tt FriCAS.hyperdoc.EmphasizeFont:} {\it font}] \ \newline
This is the font used for italics.  \xdefault{Itl14}
\item[{\tt FriCAS.hyperdoc.EmphasizeColor:} {\it color}] \ \newline
This is the color used for italics.  \xdefault{black}
\item[{\tt FriCAS.hyperdoc.InputBackground:} {\it color}] \ \newline
This is the color used as the background for input areas.
\xdefault{black}
\item[{\tt FriCAS.hyperdoc.InputForeground:} {\it color}] \ \newline
This is the color used as the foreground for input areas.
\xdefault{white}
\item[{\tt FriCAS.hyperdoc.BorderColor:} {\it color}] \ \newline
This is the color used for drawing border lines.
\xdefault{black}
\item[{\tt FriCAS.hyperdoc.Background:} {\it color}] \ \newline
This is the color used for the background of all windows.
\xdefault{white}

Note: In the past, resource names used the word Axiom instead of FriCAS.

\end{description}
