% version 0.60, 6.3.91 
% overview, introduction 

\chapter{Overview and Introduction} 

This document contains useful information 
for programming and computing with MAS.

In the first sections we discuss the 
structure of the information contained in the 
following chapters. 
In the last section we provide some hints 
on how to retrieve the information from this 
document.


\section{Specifications}

The chapter on specifications contains
some listings of first test structures.
These specifications may change in later 
versions.

The listings have been printed using 
some \LaTeX\ macros distributed by 
Eamann McManus. The macros combine two 
character tokens into one \TeX\ math--operator.
The transliteration is given in table \ref{tabTL}.

\begin{table}
\begin{center}
\begin{tabular}{|c|c|}
\hline
Modula--2 string & printed \TeX\ character \\
\hline
\verb/!=/  &  $\ne$ \\
\verb/<</  &  $\ll$ \\
\verb/<=/  &  $\le$ \\
\verb/<>/  &  $\ne$ \\
\verb/>>/  &  $\gg$ \\
\verb/>=/  &  $\ge$ \\
\verb/->/  &  $\rightarrow$ \\
\verb/:=/  &  $\leftarrow$ \\
\verb/^/   &  $\uparrow$ \\
\verb/"character string"/  &  \verb*/"character string"/ \\
\verb/'character string'/  &  \verb*/'character string'/ \\
\hline
\end{tabular}
\end{center}
\label{tabTL}
\caption{Transliteration in Listings}
\end{table}


\subsection{Overview}

The first section in this chapter contains  
an initialization data set, which reads all 
required specifications of algebraic structures 
and exposes them in the top level environment.

The second section defines some abstract structures
like Abelian Groups (\verb/AGROUP/) 
or Fields (\verb/FIELD/).

The third section contains the 
definition of all built--in structures 
such as lists (\verb/Lists/), 
booleans (\verb/BOOL/)
or atoms (\verb/ATOM/).

The fourth section contains the specifications 
of the arithmetic structures 
such as integers (\verb/INTEGER/), rational numbers (\verb/RATIONAL/), 
modular integers (\verb/MODINT/) 
or arbitrary precision floating point numbers (\verb/FLOAT/).

The fifth section defines the polynomial system 
structures 
such as integral recursive polynomials (\verb/IPOL/),
distributive rational polynomials (\verb/DIRP/),
sets (lists) of distributive rational polynomials (\verb/DIRL/) 
and rings with Gr\"obner bases (\verb/GBRING/).

The sixth section contains the definition of 
some term models such as 
propositional logic (\verb/PROPLOG/) or
Peano arithmetic (\verb/PEANO/).

The last section contains some test examples for 
the evaluation of expression using the specifications.


\section{Libraries}

The library chapters contain the 
Modula--2 definition modules of MAS.
Not contained are probably defined global variables 
of the modules.

The comments on the procedures are 
structured according the ALDES / SAC--2 
publication scheme. The first sentence of the 
comment defines the full procedure identification. 
The procedure name is a mnemonic abreviation of this 
full identification.
The remaining text describes the 
input and output parameters of the procedure 
together with a short description of 
its purpose and functionality.

The comments are extracted from the 
implementation ALDES source files so they may 
differ in some cases to the official 
publication ALDES versions. Only the 
destinction between capital letters and lower case letters 
has been introduced. 
The ornamentations are still in implementation ALDES style.
However the identifier names in the Modula--2 implementation 
modules still correspond to the implementation ALDES names.
Some care is needed in case of the function return 
parameters. They are no more visible in the 
Modula--2 procedure header, but should be 
determinable from the comment text without difficulty.

The procedure names are put to the master index
at the end of the document.

Information on the data structure definitions is 
partly contained in the {\em MAS Interactive Usage} 
document or directly in the Modula--2 implementation modules.

Some statistics on system source code sizes are 
summarized in table \ref{tabSyS}.
The indicated numbers refer to the distributed systems 
without further user contributed packages which 
may be available.

\begin{table}
\begin{center}
\begin{tabular}{|l|r|r|}
\hline
System         &   lines  &  1000 bytes \\
\hline
MAS 0.6        &   42023  &    1 484    \\
Reduce 3.3     &   51661  &    1 665    \\
Scratchpad II  &   66382  &    2 402    \\
\hline
\end{tabular}
\end{center}
\label{tabSyS}
\caption{System Source Code Sizes}
\end{table}


\section{Indexes}

There are three indexes:
\begin{enumerate}
\item a procedure header to definition module index,
\item a comment to procedure name index and
\item a master index of procedure names.  
\end{enumerate}
In the sequel we discuss the definition of each index.

In case of the procedure header to definition module index 
each line is build as follows:
\begin{enumerate}
\item The first column shows the 
      name of the Modula--2 definition module. 
      The file name extension \verb/.DEF/ is not shown.
\item The second column shows the 
      Modula--2 (ALDES / SAC--2) procedure name. 
\item The rest of the line shows the 
      input and output parameters of the procedures.
\item The index is alphabeticaly sorted by the second column.
\end{enumerate}

In case of the comment to procedure name index
each line is build as follows:
\begin{enumerate}
\item The first column shows the 
      name of the Modula--2 (ALDES / SAC--2) procedure. 
\item The second column shows the 
      name identifying comment sentence. 
\item The index is alphabeticaly sorted by the second column.
\end{enumerate}

Finally the master index of procedure names contains 
all names of procedures listed in the definition modules.
The numbers following the procedure name show the 
page number in this document where the procedure comment 
is listed. 


\section{How to Use the Indexes}

There are three main usages of this document 
\begin{enumerate}
\item you know the procedure name and you want to know 
      the procedure parameters or the procedure location.
\item you have some idea of a procedure function and 
      want to know if there exists a procedure which 
      implements this function.
\item you know the procedure name and want to know the 
      description of the functionality of the procedure.
\end{enumerate}

The first problem can be solved in two ways:
\begin{enumerate}
\item You search the procedure name in the 
      procedure header to definition module index. 
      From the found entry the number of parameters and 
      (in most cases) from the parameter names 
      the types of the parameters can be determined. 
\item Or you search the procedure name in the 
      master index. 
      From the found entry the page number of the 
      procedure comment can be determined. 
      Looking at this page the description of 
      the procedure parameters together with  
      the functionality of the procedure can be determined.
\end{enumerate}

For the second problem there are also two solutions:
\begin{enumerate}
\item You search for an procedure comment in the  
      comment to procedure name index. 
      From the found entry the names of the desired 
      procedures can be determined.
\item You search in the table of contents 
      for the definition module with the required functionality.
      Then from the listing of the definition module
      the existance of an appropriate procedure 
      can be determined. 
\end{enumerate}

For the third problem there is only one recomendable  
solution:
\begin{enumerate}
\item You search the procedure name in the 
      master index. 
      From the found entry the page number of the 
      procedure comment can be determined. 
      Looking at this page the description of 
      the procedure parameters together with  
      the functionality of the procedure can be determined.
\end{enumerate}

Note that for the interactive use of MAS it is required that 
you check if the procedure is accessible from the 
interpreter by the HELP or EXTPROCS command.

