@comment -*-texinfo-*-
@comment $Id: general.doc,v 1.50 1998-05-12 09:09:37 schmidt Exp $
@comment this file contains the general information about Singular

@c The following directives are necessary for proper compilation
@c with emacs (C-c C-e C-b).
@c %**start
@c \input texinfo.tex
@c @setfilename general.info
@c @node Top, General concepts
@c @menu
@c * General concepts::
@c @end menu
@c @node General concepts, Data types, Introduction, Top
@c @chapter General concepts
@c %**end

@menu
* Interactive use::
* Rings and orderings::
* Implemented algorithms::
* The SINGULAR language::
* Procedures::
* Libraries::
* Debugging tools::
@end menu


@c ---------------------------------------------------------------------------
@c ---------------------------------------------------------------------------
@node Interactive use, Rings and orderings, General concepts, General concepts
@section Interactive use
@cindex Interactive use

@menu
* How to enter and exit::       
* SINGULAR prompt::             
* The online help system::      
* Interrupting SINGULAR::       
* Editing input::               
* Control parameters::          
* Startup sequence::            
* Reuse of output::             
* Commandline options::         
@end menu

@c --------------------------------------------------------------------------
@node How to enter and exit,SINGULAR prompt  , Interactive use, Interactive use
@subsection How to enter and exit
@cindex How to enter and exit

To start @sc{Singular}, enter @code{Singular} at the system prompt.
@*You get a header which, among others, reports the version name and
compilation date.
Enter @code{help;} to get the online manual at the @sc{Singular} prompt
@code{>}.
Commands are always need to be ended by a @code{;} (semicolon) and
@code{<ENTER>}. @*To exit @sc{Singular} type @code{quit;}, @code{exit;}
or @code{$}. 


@sc{Singular} may also be started with command-line options and with
filenames as arguments. More generally, the synopsis of @sc{Singular} is
@*@code{  Singular  [options] [file1 [file2 ...]] }

@ref{Commandline options}
@menu
* Commandline options::
@end menu

@*On start-up, @sc{Singular}
@enumerate
@item
loads the library @code{standard.lib} (provided the @code{--no-stdlib}
was not given)

@item
searches the current directory and then the
home directory of the user for a file named @code{.singularrc} and
executes it, if found (provided the @code{--no-rc} options was not
given)

@item
executes the files @code{file1}, @code{file2} ...  (given on the command
line) in that order.
@end enumerate

Unless specified otherwise, @sc{Singular} locates all (data) files and
libraries by first searching the current working directory,
and then by searching through all the directories specified by the
environment variable @code{SINGULARPATH} (@code{SPATH} on DOS-based
systems), and, finally, by searching through some default directories
(e.g., @code{/usr/local/share/Singular}).

@c --------------------------------------------------------------------------
@node SINGULAR prompt,The online help system,How to enter and exit, Interactive use
@subsection SINGULAR prompt
@cindex SINGULAR prompt
@cindex prompt
@cindex error recovery
The @sc{Singular} prompt @code{>}
asks the user for input of a command, while the prompt @code{.}
asks the user for input of missing parts of a command (remember the
semicolon @code{;} at the end of every command). If your input
is erroneous @sc{Singular} may miss the semicolon.
(It may be missed because @sc{Singular} needs first a @code{"} or @code{@}}.)
On the other hand additional @code{;} will not harm @sc{Singular}:
extra semicolons are interpreted as empty statements.

@c --------------------------------------------------------------------------
@node The online help system,Interrupting SINGULAR,SINGULAR prompt,Interactive use
@subsection The online help system
@cindex The online help system

@sc{Singular} uses @code{info} (from @code{texinfo}) for it's help system.@*
The whole manual is decomposed into "nodes" of information.
A node contains text describing a specific topic at a specific level of
detail. The top line of a node is its "header".  This node's header
(the upper most line) tells the name of this node (@code{Node:}),
the name of the next node (@code{Next:}),
the name of the previous node (@code{Prev:}),
and the name of an "Up" node (@code{Up:}).

To move within info type commands of single characters and do not type a RETURN
character. The most important commands:
@table @asis
@item @code{q}
leave info
@item @code{n}
go to the "next" node
@item @code{p}
go to the "previous" node
@item @code{u}
go to the "up" node
@item @code{m}
pick a menu item specified by name. Reads name of menu entry
@item @code{f}
follow a cross reference.  Reads name of reference
@item @code{l}
go to the previous visited node
@item @code{h}
help about info (use @code{l} to come back)
@item @code{b}
go to the begining of the current node
@item @code{e}
go to the end of the current node
@item SPACE
scroll forward a page
@item DEL
scroll backward a page
@item @code{s}
search through this Info file for a specified string,
and select the node in which the next occurrence is found
@end table
@c --------------------------------------------------------------------------
@node Interrupting SINGULAR,Editing input,The online help system,Interactive use
@subsection Interrupting SINGULAR
@cindex Interrupting SINGULAR

Typing @code{CTL-C} (control C) interrupts Singular (system dependend).
@sc{Singular} prints the current command and the current line.
You have the following choices:
@table @asis
@item @code{a}
return to the toplevel after finishing the current command
@item @code{c}
continues
@item @code{q} 
quits  @sc{Singular}
@end table

@c --------------------------------------------------------------------------
@node Editing input,Control parameters,Interrupting SINGULAR,Interactive use
@subsection Editing input
@cindex Editing input

If the command line option @code{-t} is not given,
@sc{Singular} redefines the terminal characteristics
@footnote{
therefore the comandline option @code{-t} must be given if @sc{Singular} should
run in the background
}
and the following keys can be used for editing
the input and retrieving previous input lines
(CTL denotes the control key):
@table @kbd
@item CTL-A
go to the start of the line
@item CTL-B
go one character to the left
@item CTL-D
erase the character under the cursor
(or return @kbd{EOF}, if the current line is empty)
@item CTL-E
go to to the end of the line
@item CTL-F
go one character to the right
@item BACKSPACE
@itemx DELETE
@itemx CTL-H
erase the character before the cursor
@item CTL-K
kill the rest of the line
@item CTL-N
save the current line to the history and get the next line
@item CTL-P
save the current line to the history and get the previous line
@item CTL-U
kill the whole line
@item RETURN
save the current line to the history and
send it to the @sc{Singular} parser for interpretation
@end table
@* @strong{Remarks:}
@* This section does not apply to the MPW-Macintosh version of
@sc{Singular}.
@* This section describes only a subset of the key bindings of
@sc{Singular} binaries built with GNU @code{Readline} library. 
See the @code{RXSeadline} manual for the key bindings.

@c --------------------------------------------------------------------------
@node Control parameters, Startup sequence, Editing input, Interactive use
@subsection Control parameters
@cindex Control parameters

You may wish to set some control parameters. Most often used are
@code{timer}, @code{option(prot)} and @code{pagewidth}.

@itemize @bullet
@item
If @code{timer} is set to 1 the time (in sec) used for the execution of
a command
is displayed if it is bigger than 0.5 sec (Unix: CPU-time
or Macintosh/MSDOS: time between two commands).
@item
@code{option(prot)} shows a short protocol during std-computation: the
number between brackets () is the number of critical pairs still
to be reduced (except immediatly after an H 'high corner' where it shows the
degree above which all monomials can be discarded), a - sign indicates
that one critical pair has been reduced (either to 0 or to a new
s-polynomial which indicated by an s), a number without brackets
shows the degree in which the computation takes place (this is in
particular useful if the input is homogeneous).
There are many more options, mostly used to control the strategies
for the std-computations, see the manual or type @code{help option;}.
@item
@code{pagewidth} sets the number of characters in a line printed on the
screen.
@item
@code{option} also controls messages like warnings, loading libs, etc.
@xref{option}, or type @code{help verbose;}.
@end itemize

@example
pagewidth = 80;        // set pagewidth to 80 characters
option(prot);          // short protocol
timer = 1;             // activate the timer
option(noredefine);   // supress redefine-warnings
@end example

The file @code{.singularrc} can be used to set your preferred
parameters. If you start @sc{Singular} this file is automatically loaded
such that your parameters are set (see @ref{Startup sequence}).

@c --------------------------------------------------------------------------
@node Startup sequence, Reuse of output, Control parameters, Interactive use
@subsection Startup sequence
@cindex Startup sequence

@c --------------------------------------------------------------------------
@node Reuse of output, Commandline options, Startup sequence, Interactive use
@subsection Reuse of output
@cindex Reuse of output

The most recently printed expression is available
under the special name @code{_}, e.g.
@example
@c example
  ring r;
  ideal i=x2+y3,y3+z4;
  std(i);
  ideal k=_;
  k*k+x;
  size(_[3]);
@c example
@end example

@c --------------------------------------------------------------------------
@node Commandline options, ,Reuse of output,Interactive use
@subsection Commandline options
@cindex Commandline options

The synopsis of @sc{Singular} is

@*@code{  Singular  [options] [file1 [file2 ...]] }

@*Options can be given in both, their long and short format. The following
options control the general behaviour of @sc{Singular}:
@table @asis

@item @code{-e}, @code{--echo[=VAL]} 
Set value of variable @code{echo} to @code{VAL} (integer in the range 0
.. 9). Without an argument, @code{echo} is set to 1, which echoes all
input coming from a file. By default, the value of @code{echo} is 0. See
also @ref{echo}.

@item @code{-h}, @code{--help} 
Print a short help message and a one line description of each command 
line option.

@item @code{--no-rc}               
Do not execute the @code{.singularrc} file on start-up. By default,
@sc{Singular} searches first in the current directory and then in the
home directory of the user for a file named @code{.singularrc}. If it is 
found, then it is executed after the library @code{standard.lib} is
loaded and prior to executing the string specified by
@code{--user-option}. See also @ref{Startup sequence}.

@item @code{--no-stdlib}
Do not load the library @code{standard.lib} on start-up. By default,
this library is loaded on start-up. See also @ref{Startup sequence}.

@item @code{-t}, @code{--no-tty} 
Do not redefine the terminal characteristics (useful for batch
processes, see @ref{Editing input}).  

@item @code{-q}, @code{--quiet}
Do not print start-up banner and warnings and redirect stderr (all error
messages) to stdout (normal output channel). This option should be used
if the output is redirected to a file.

@item @code{-v}, @code{--verbose}             
Print extended information about the version and configuration of
@sc{Singular}  (used optional parts, compilation date, start of random
generator etc.). This information should be included if a user reports
an error to the authors.
@end table

The following command line options allow manipulation of the timer and
the pseudo random generator and passing of commands and strings to 
@sc{Singular}:

@table @asis
@item @code{-c}, @code{--execute=STRING} 
Execute @code{STRING} as (a sequence of) @sc{Singular} commands on
start-up after the @code{.singularrc} file is executed, but prior to
executing the files given on the command line, e.g.  @code{Singular -c
"help all.lib; quit;"} shows the help for the library @code{all.lib} and
exits.

@item @code{-u}, @code{--user-option=STRING}
Returns @code{STRING} on @code{system("--user-option")}. This is useful
for passing arbitrary arguments (like filenames) from the command line
to the @sc{Singular} interpreter (i.e. top-level of @sc{Singular}), e.g.
@code{Singular -u "xxx.dump" -c 'getdump(system("--user-option"))'}
reads the file @code{xxx.dump} at startup and allows the user to start working
with all the objects defined in the previous session.

@item @code{-r}, @code{--random=SEED}
Seed (i.e., set initial value of) pseudo random generator with integer
@code{SEED}. If this option is not given, then the
random generated is seeded with a time-based @code{SEED} (e.g., the
number of seconds since January, 1, 1970, on Unix systems).

@item @code{--min-time=SECS} 
If the @code{timer} (resp.  @code{rtimer}) variables is set, do only
report times larger than @code{SECS} seconds (@code{SECS} needs to be a
floating point number greater than 0). By default, this value is set to
0.5 (i.e., half a second), e.g. the option @code{--min-time=0.01} forces
Singular to report all times larger than 1/100 of a second.

@item @code{--ticks-per-sec=TICKS} 
Sets unit of timer to @code{TICKS} per second (i.e. the value reported
by the @code{timer} and @code{rtimer} variable divided by @code{TICKS}
gives the time in seconds). By default, this value is 1.

@end table

The last 3 options are of interest for the use with MP links:
@table @asis
@item @code{-b}, @code{--batch} 
Run in MP batch mode. Opens a TCP/IP connection with host specified by
@code{--MPhost} at the port specified by @code{--MPport}. Input is read
from and output is written to this connection in the MP format. See also
@ref{MPtcp links}.

@item @code{--MPport=PORT}
Use @code{PORT} as default port number for MP connections (whenever not
further specified) . This option is mandatory when the @code{--batch}
option is given. See also @ref{MPtcp links}.

@item @code{--MPhost=HOST}
Use @code{HOST} as default host for MP connections (whenever not
further specified) . This option is mandatory when the @code{--batch}
option is given. See also @ref{MPtcp links}.

@end table
The value of options given to @sc{singular} (resp. their default values, 
if an option was not given), can be checked with the command
@code{system(LongOptionNameString)}. See also @ref{system}.  
@strong{Example:}
@example
@c example
system("--quiet");    // if "quiet" 1, otherwise 0
system("--min-time"); // minimal reported time 
@c example
@end example
@c --------------------------------------------------------------------------
@c ---------------------------------------------------------------------------
@node Rings and orderings, Implemented algorithms, Interactive use, General concepts
@section Rings and orderings
@cindex Rings and orderings

@menu
* Available rings::
* General syntax of a ring definition::
* Term orderings::
@end menu

@c ---------------------------------------------------------------------------
@node Available rings, General syntax of a ring definition, Rings and orderings, Rings and orderings
@subsection Available rings
@cindex Available rings

Almost all computations in @sc{Singular} require a basering which may be
@itemize @bullet
@item
a polynomial ring over a field
@item
a series ring, i.e a localization of a polynomial ring
@item
a factor ring by an ideal of one of the above
@item
a tensor products of one of the above
@end itemize

Each object of type
@code{map},
@code{matrix},
@code{module},
@code{number},
@code{ideal},
@code{poly},
@code{resolution},
@code{vector}
belongs to a specific ring.
Also @code{list}, if one of the objects belong to a ring.
These objects are local to the ring, hence their names can be used for other
objects in other rings.
Objects from one ring can be mapped to another
ring with an object of type @code{map}
(or with the commands @code{fetch} or @code{imap}).
They are all algebras over the ground
field. Hence, in order to compute in one of the ground fields,
one has to define a ring (with at least one variable and a monomial
ordering).

The ground field of these algebras may be
@itemize @bullet
@item
the rational numbers Q (char 0)
@item
a finite field Z/p, p a prime <= 32003 (char p)
@item
@tex
\noindent a finite field with $q=p^n$ elements ($p^n<=\le 2^{15}$)
@end tex
@ifinfo
a finite field with q=p^n elements (p^n<=2^15)
@end ifinfo
@item
transcendental extension K(A,B,C,...), K=Q or Z/p
@item
algebraic extension K[Z]/MinPol, K=Q or Z/p
@item
floating point real numbers with simple precision (real)
@end itemize

The other types do not belong to a ring and can be accessed within every ring.

@c ---------------------------------------------------------------------------
@node General syntax of a ring definition, Term orderings, Available rings, Rings and orderings
@subsection General syntax of a ring definition
@cindex General syntax of a ring definition

@c ------------------------------------------------------------
@c   This piece of text (partially) exists also in the 
@c   file types.doc, chapter "ring declarations".
@c   If you change something here, change it there, too!
@c ------------------------------------------------------------
@table @code
@item @strong{Syntax:}
@code{ring} name @code{=} field@code{,}
  @code{(} names_of_ring_variables @code{),}
  @code{(} ordering @code{);}
@item @strong{Default:}
@code{32003,(x,y,z),(dp,C);}
@item @strong{Purpose:}
defines a basering for polynomials, ideals, vectors, modules, resolutions
and matrices and set it as the actual basering.

All advanced algorithms in @sc{Singular} require a ring.
The last defined ring is the basering until a new ring is defined
or until it is changed with @code{setring} or @code{keepring} or
it gets killed.

The coefficient field is given by either
@enumerate
@item
the characteristic (0 or a prime <= 32003)
@item
an expression_list of the characteristic and
the names of  parameters.
If there is only one parameter you may define a minimal polynomial for it
to work in an algebraic extension of Q or F(p).
See @ref{minpoly}
@item
an expression_list of the number of element
(a small prime characteristic p to the power of a small exponent n) and a
name for a primitive element (generating the multiplicative group).
The maximal values for p and n depend on the files in the directory @code{gftables}.
They define the finite field with p^n elements.
@item
the name @code{real}. The field elements will be the machine floating
point numbers.
@end enumerate

@*If you write a  characteristic which is not a prime,
it is automatically converted
to the next lower prime or you receive an error message.

The names of ring variables
are like variable names (comma separated).

The ordering is a list of blockorderings which have an order keyword and
a weight vector or an optional size.

Possible order keywords are:
@itemize @bullet
@item @code{lp}, @code{dp}, @code{Dp}, @code{ls}, @code{ds}, @code{Ds}, @code{M}
with optional size parameter

@item @code{wp}, @code{Wp}, @code{ws}, @code{Ws}
with weight vector

@item @code{c}, @code{C}
for components orders

@end itemize

If one element of the list consists of only one entry, the parentheses may
be omitted.
@item @strong{Example:}
@example
  ring r =
  32003,       // coefficient field: Z/32003
  ( x,y,z ),   // names for variables
  ds;          // monomial ordering
               // (degrevlex in a series ring)
               // parenthesis of lists with only one element
               // are optional
@end example
@example
  ring r2=10,(x(1..6)),(lp(2),dp(4));
               // defines a ring with name r2,
               // (10 is substituted by the next lower prime)
               // coefficient field: Z/7
               // variables x(1),x(2),..,x(6)
               // which is the polynomial ring (Z/7)[x(1),..,x(6)]
               // with lexicographical ordering on x(1) and x(2)
               // and then
               // degree reverse lexicographical on x(3)..x(6)
@end example
@example
  ring r3=0,(x,y,z,a,b,c),(ds(3), dp(3));
               // defines a ring with name r3,
               // coefficient field Q
               // variables x,y,z,a,b,c
               // which is the ring (Q[a,b,c])[x,y,z]_(x,y,z)
@end example
@example
  ring r4=0,(x,y,z),(c,dp);
               // defines a ring with name r4,
               // coefficient field Q (rationals)
               // variables x,y,z
               // which is the polynomial ring Q[x,y,z]
               // with ordering of vectors by
               // first number of the component and then
               // degree reverse lexicographical on x,y,z
@end example
@example
  ring r5=(7,a),(x,y,z),dp;
               // defines a ring with name r5,
               // coefficient field K=(Z/7)(a)
               // variables x,y,z
               // which is the polynomial ring K[x,y,z]
               // with ordering
               // degree reverse lexicographical on x,y,z
@end example
@example
  ring r6=(7,a),(x,y,z),dp;
  minpoly=a^2+a+3;
               // defines a ring with name r6,
               // coefficient field K=(Z/7)[a]/a^2+a+3
               // (the finite field with 49 elements)
               // variables x,y,z
               // which is the polynomial ring K[x,y,z]
               // with ordering
               // degree reverse lexicographical on x,y,z
@end example
@example
  ring r7=(7^2,a),(x,y,z),dp;
               // defines a ring with name r7,
               // the same ring as r6
               // this option is offered for
               // a few powers of primes
               // (see file gftable/49)
               // the computations are faster
               // in this representation
@end example
@example
  ring r8=(181,A,B,Z),(x,y,z),dp;
               // defines a ring with name r8
               // coefficient field K=Z/181(A,B,Z)
               // variables x,y,z
               // which is the polynomial ring K[x,y,z]
               // degree reverse lexicographical on x,y,z
@end example
@example
  ring r9=real,(x,y,z),dp;
               // defines a ring with name r9
               // coefficient field R
               // (represented as floating point numbers)
               // variables x,y,z
               // which is the polynomial ring R[x,y,z]
               // degree reverse lexicographical on x,y,z
  number n=1.7e+2; // input format of real numbers
@end example

@item @strong{Note:}
Computations in rings with one parameter are faster
than computations with more parameters. (Cancellation of common factors
are only implemented in the first case)

@* Computation over the field @code{real} has computing errors because
of rounding.
@item @strong{Use in procedures:}
All changes of the basering by a definition of a new @code{ring} or a
@code{setring} command in a procedure are local to this procedure
(i.e. will not affect the calling procedure) unless a @code{keepring}
command is used.
@end table
@menu
* ring::
* Term orderings::
* qring:: define quotient rings
* charstr:: the coefficient field
* npars:: number of parameters
* nvars:: number of variables
* ordstr:: the monomial ordering
* parstr:: the parameters
* par:: the parameter as number
* varstr:: the ring variables
* var:: the ring variables as poly
* setring:: a local ring change
* keepring:: ring change in the next (upper) level
@end menu
@iftex
See @ref{ring}; @ref{Term orderings};
@ref{qring}; @ref{charstr}; @ref{npars};
@ref{nvars}; @ref{ordstr};
@ref{varstr}; @ref{var}; @ref{setring}; @ref{keepring}.
@end iftex

@c ---------------------------------------------------------------------------
@node Term orderings, ,General syntax of a ring definition, Rings and orderings
@subsection Term orderings
@cindex Term orderings

The most important term orderings or monomial orderings in @sc{Singular} are:
@*global or p-orderings: @code{lp, dp, wp, Dp, Wp} refer to a polynomial ring,
@*local or s-orderings: @code{ls, ds, ws, Ds, Ws} refer to a series ring,
@*matrix orderings: allow to create any ordering by a matrix,
@*product (or block) orderings of the above.

Given such an ordering say, ord, the ring r created by
@*@center @code{ring r = p,x(1..n),ord;}
@*
@tex
is by definition Loc K$[x_1,...,x_n]$, where K=Z/p and Loc denotes
localization with respect to the muliplicatively closed set
$$\{ 1+f | lead(f) < 1 \}.$$
Here lead means the leading monomial with respect to ord, 1
is the constant monomial 1 and $>$ means bigger with respect to
ord. For global orderings, $x_i > 1$, hence Loc K$[x_1,...,x_n]$ =
K$[x_1,...,x_n]$, for local orderings, $x_i < 1$, hence LocK$[x_1,...,x_n]$ =
Loc$_{(x)}$K[$x_1,...,x_n$] (= localization of K[$x_1,...,x_n$] with
respect to the maximal ideal $(x_1,...,x_n)$).
A product ordering which is for example
of the form (s-ordering(k),p-ordering(l)), n=k+l, (the variables
$x1,...,xk$ being s-ordered, $x_{k+1},...,x_n$ p-ordered) creates
           Loc$_(x)$K[$x_1,...,x_k] \otimes $K[$x_{k+1},...,x_n$].
Many other rings between the polynomial ring and the power
series ring are realized by the choice of an ordering.
@end tex
@ifinfo
is by definition Loc K[x(1),...,x(n)], where K=Z/p and Loc denotes
localization with respect to the muliplicatively closed set
@*@center @{ 1+f | lead(f) < 1 @}.
@*Here lead means the leading monomial with respect to ord, 1
is the constant monomial 1 and > means bigger with respect to
ord. For global orderings, x(i) > 1, hence Loc K[x(1),...,x(n)] =
K[x(1),...,x(n)], for local orderings, x(i) < 1, hence LocK[x(1),...,x(n)] =
Loc_(x)K[x(1),...,x(n)] (= localization of K[x(1),...,x(n)] with respect to the
maximal ideal (x(1),...,x(n))). A product ordering which is for example
of the form (s-ordering(k),p-ordering(l)), n=k+l, (the variables
x(1),...,x(k) being s-ordered, x(k+1),...,x(n) p-ordered) creates
           Loc_(x)K[x(1),...,x(k)] tensor K[x(k+1),...,x(n)].
Many other rings between the polynomial ring and the power
series ring are realized by the choice of an ordering.
@end ifinfo

The great variety of differnt orderings and their efficient
implementation makes @sc{Singular} a powerful tool for many different tasks
in Algebraic Geometry, Algebra and Singularity theory.

On the other hand it requires careful thinking about the 'correct'
ordering for a specific task. Even if the rings are the same,
the result of a standard basis computation depends on the
ordering. For instance, the commands dim, mult, degree, hilb,
etc. compute the dimension, multiplicity, etc. of the ideal
generated by the leading terms of the given generators. In
many cases of interest, e.g. if a degree-ordering is choosen
and if the generators are a standard basis, the computed
result will be the corresponding invariant of the ideal itself.
Nevertheless, it remains the task of the user to give a correct
interpretation of the result.

@iftex
--------------------------------------------------------------------------
@end iftex

@tex
A monomial ordering (term ordering) on $K[x_1, \ldots, x_n]$ is
a total ordering $<$ on the
set of monomials (power products) $\{x^\alpha|\alpha \in \bf{N}^n\}$
which is compatible with the
natural semigroup structure, i.e.\ $x^\alpha < x^\beta$ implies $x^\gamma
x^\alpha < x^\gamma x^\beta$ for any $\gamma \in \bf{N}^n$.
We do not require
$<$ to be  a wellordering.
@end tex
@ifinfo
A monomial ordering (term ordering) on $[x_1, ..., x_n] is
a total ordering < on the
set of monomials (power products) @{x^a | a in N^n@}
which is compatible with the
natural semigroup structure, i.e. x^a < x^b implies x^c*x^a < x^c*x^b for any
c in N^n.
We do not require
< to be  a wellordering.
@end ifinfo
See the literature cited in @ref{Introduction}, (section 'Background').

@sc{Singular} offers the following monomial orderings which are implemented
in an effective way:
@menu
* Global orderings:: lp, dp, wp, Dp, Wp.
* Local orderings:: ls, ds, ws, Ds, Ws.
* Module orderings:: c, C.
* Matrix orderings:: M.
* Product orderings::
* Extra weight vector:: a.
@end menu
@iftex
@itemize @bullet
@item
global orderings or p-orderings: @code{lp, dp, Dp, wp, Wp} (p refers to polynomial ring)
@item
local orderings or s-orderings: @code{ls, ds, Ds, ws, Ws} (s refers to series ring)
@item
module orderings @code{c, C} (ordering of the components of a vector)
@item
matrix orderings @code{M} (may be used to define any allowed ordering)
@item
any of the above orderings may be combined to yield product or
block orderings.
@item
ordering @code{a} (inserting an extra weight vector)
@end itemize
@end iftex

@tex
Global orderings are wellorderings (i.e.\ $1 < x_i$ for each variable
$x_i$), local orderings satisfy $1 > x_i$ for each variable.   If some variables are ordered globally and others locally we
call it a mixed ordering.   Local or mixed orderings are not wellorderings.

If $K$ is the groundfield, $x = (x_1, \ldots, x_n)$ the
variables and $<$ a monomial ordering, then {\bf Loc K}$[x]$ denotes the
localization of $K[x]$ with respect to the multiplicatively closed set $\{1 +
g \mid g = 0$ or $g \in K[x]\backslash \{0\}$ and $L(g) < 1\}$.   $L(g)$
denotes the leading monomial of $g$, i.e.\ the biggest monomial of $g$ with
respect to $<$.   The result of any computation which uses standard basis
computations has to be interpreted in {\bf Loc K}$[x]$ (like @code{std, syz, res,
mres, sres, mult, degree, dim, hilb, mstd}, etc.).
@end tex
@ifinfo
Global orderings are wellorderings (i.e.1 < x_i for each variable
x_i), local orderings satisfy 1 > x_i for each variable.
If some variables are ordered globally and others locally we
call it a mixed ordering.   Local or mixed orderings are not wellorderings.

If K is the groundfield, x = (x_1, @dots{}, x_n) the
variables and < a monomial ordering, then Loc K[x] denotes the
localization of K[x] with respect to the multiplicatively closed set @{1 +
g | g = 0 or g in K[x]\@{0@} and L(g) < 1@}.   L(g)
denotes the leading monomial of g, i.e. the biggest monomial of g with
respect to <.   The result of any computation which uses standard basis
computations has to be interpreted in Loc K[x] (like @code{std, syz, res,
mres, sres, mult, degree, dim, hilb, mstd}, etc.).
@end ifinfo


@c ---------------------------------------------------------------------------
@c ---------------------------------------------------------------------------
@node Implemented algorithms, The SINGULAR language, Rings and orderings, General concepts
@section Implemented algorithms
@cindex Implemented algorithms


The basic algorithm in @sc{Singular} is a general standard basis algorithm for
any monomial ordering which is compatible with the natural semigroup
structure of the exponents. This includes wellorderings (Buchberger algorithm)
and tangent cone orderings (Mora algorithm) as special cases.

Different syzygy algorithms, free resolutions (@code{sres, res, mres}) for computation of free resolutions
of modules over the above rings are implemented.

Combinatorial algorithms for computing dimensions, hilbert series, multiplicities, ...

An algorithm for uni- and multivariate polynomial factorization.

See the file 'singular_algorithms.tex' for details and further algorithms.

@table @code
@item @strong{Commands to compute standard bases}
@table @asis
@item @code{facstd}
@ref{facstd}
@*computes the a list of Groebner bases via the Factorizing Groebenr Basis Algorithm: the intersection of the zero sets is the zero set of the given ideal
@item @code{fglm}
@ref{fglm}
@*computes the Groebner basis provided that a reduced Groebner basis w.r.t.
another ordering is known
@*The given ideal must be zero-dimensional.
@item @code{std}
@ref{std}
@*computes the standard and Groebner basis
(depending on the @code{ring} definition, see @ref{Rings and orderings}
and the options, see @ref{option})
@item @code{stdfglm}
@ref{stdfglm}
@*computes the Groebner basis in a ring with a "difficult" ordering
(i.e. lexicographical, ...) via @code{std} w.r.t. a "simple" ordering and
@code{fglm}
@*The given ideal must be zero-dimensional.
@item @code{stdhilbert}
@ref{stdhilbert}@*
computes the Groebner basis in a ring with a "difficult" ordering
(i.e. lexicographical, ...) via @code{std} w.r.t. a "simple" ordering and
a @code{std} computation guided by the hilbert series
(see @ref{hilb}, @ref{std})
@end table
@item @strong{Further processing of standard bases}
@table @asis
@item @code{degree}
@ref{degree}@*
computes the (Krull) dimension, codimension and the multiplicity
@item @code{dim}
@ref{dim}@*
computes the dimension of the ideal/module generated by
the leading monomials of the generators representing the given
ideal/module. This is also the dimension of the ideal if it is represented by
a standard basis.
@item @code{mult}
@ref{mult}@*
computes the degree of the monomial ideal/module generated by
the leading monomials of the input.
@item @code{reduce}
@ref{reduce}@*
reduces a polynomial, vector, ideal  or module
to its normal form with respect to an ideal or module represented
by a standard basis.
Return 0 if and only if the polynomial (resp. vector, ideal, module)
is an element (resp. subideal, submodule) of the ideal (resp. module).
@item @code{vdim}
@ref{vdim}@*
computes the vector space dimension of the ring (resp. free module)
modulo the ideal (resp. module)
@end table
@item @strong{Commands to compute resolutions}
@table @asis
@item @code{minres}
@ref{minres}@*
minimizes a free resolution of an ideal or module
@item @code{lres}
@ref{lres}@*
computes a free resolution of an ideal or module with LaScala's
method. The input should to be homogeneous.
@item @code{mres}
@ref{mres}@*
computes a minimal free resolution of an ideal or module
with the syzygy method.
@item @code{res}
@ref{res}@*
computes a free resolution of an ideal or module.
@*Depending on the input, the current ring and the options
@sc{Singular} chooses different algorithms: the syzygy method, Schreyer's method
or LaScala's method.
@item @code{sres}
@ref{sres}@*
computes a free resolution of an ideal or module with Schreyer's
method. The input has to be a standard basis.
@item @code{syz}
@ref{syz}@*
copmutes the first syzygy (i.e. the module of relations of the
given generators)
@end table
@item @strong{Further processing of resolutions}
@table @asis
@item @code{betti}
@ref{betti}@*
compute the graded Betti numbers of a module from a free resolution
@item @code{minres}
@ref{minres}@*
minimizes a free resolution of an ideal or module
@end table
@item @strong{Processing of polynomials}
@table @asis
@item @code{extgcd}
@ref{extgcd}@*
@item @code{factorize}
@ref{factorize}@*
@item @code{gcd}
@ref{gcd}@*
@end table
@item @strong{Commands for matrices}
@table @asis
@item @code{bareiss}
@ref{bareiss}@*
@item @code{det}
@ref{det}@*
@item @code{resultant}
@ref{resultant}@*
@end table
@item @strong{Commands to compute characteristic sets}
@table @asis
@item @code{char_series}
@ref{char_series}@*
@end table
@end table


@c ---------------------------------------------------------------------------
@node The SINGULAR language, Procedures, Implemented algorithms, General concepts
@section The SINGULAR language
@cindex The SINGULAR language

@sc{Singular} has a comfortable programming language similar to C
with @code{for}, @code{if} ... @code{else}, @code{while}   etc.

It is interpreted. Every user has therefore a convinient way
to write procedures (or libraries) for his own purposes, using
the functions of the kernel of @sc{Singular} and from other libraries.

See the section 'Writing procedures' of the tutorial.

@menu
* General command syntax::
* Special characters::
* Names and objects::
* Type conversion and casting::
* Flow control::
@end menu

@c ---------------------------------------------------------------------------
@node General command syntax, Special characters, The SINGULAR language, The SINGULAR language
@subsection General command syntax
@cindex General command syntax

The general form of a command is (with optional parts in square brackets):
@itemize @bullet
@item
a @strong{definition}:
@*   type_name name [ @code{=} expression ] @code{;}
@* @strong{Example:}
@example
  ring r;              // creates the default ring
  poly f = x^2 + y^3 ; // define polynomial f=x^2+y^3
  poly g=xy+z2;        // define polynomial g=x*y+z^2
  ideal I = f,g;       // ideal generated by f and g
  matrix m[3][3];      // creates a 3 x 3 zero matrix
  int i=2;             // define the integer i and set i to 2
@end example

For more information on declarations, see @ref{Names and objects}.
@item
an @strong{assignment}:
@*   name  @code{=} expression @code{;}
@*   name @code{=} expression_list @code{;}
@* @strong{Example:}
@example
  f = x^2 + y^2 ;      //overwrites the old value of f
  I = jacob(f);
  f,g = I[1],x^2+y^2 ; //overwrites the old values of f and g
@end example
@item
a @strong{command}:
@*   command_name [ @code{(} argument_list @code{)} ] @code{.}
@* @strong{Example:}
@example
  degree(I);
@end example
@item
a @strong{print command}:
@*   expression @code{;}
@*   @code{type} name @code{;}
@*   @code{print(} expression @code{);}
@* @strong{Example:}
@example
@c example
  int i=2; i;
  type i;              // name [ level ] type value
  print(i);
@c example
@end example
@end itemize


@c ------------------------------------------------------------
@node Special characters, Names and objects, General command syntax, The SINGULAR language
@subsection Special characters
@cindex Special characters
The following characters/operators have special meanings:
@table @asis
@item @code{=}
assignment
@item @code{(}, @code{)}
in expressions, for indexed names and for argument lists
@item @code{[}, @code{]}
access operator for strings, integer vectors, ideals, matrices,
polynomials, and lists.  Used to build vectors of polynomials.
Examples: @code{s[3]}, @code{m[1,3]}, @code{i[1..3]},
@code{[f,g+x,0,0,1]}.
@item @code{+}
addition
@item @code{-}
subtraction
@item @code{*}
multiplication
@item @code{/}
division of numbers (coefficients of polynomials) and polynomials
@item @code{%}
integer modulo
@item @code{^} or @code{**}
exponentiation
@item @code{==}
equal.  E.g. @code{if (i==j)...}
@item @code{!=} or @code{<>}
not equal.  E.g. @code{if (i<>j)...}
@item @code{>=}
bigger or equal
@item @code{>}
bigger
@item @code{<=}
smaller or equal
@item @code{<}
smaller, but also used for file input.  @xref{filecmd}.
@item @code{!}
synonym for @code{not}
@item @code{&&}
synonym for @code{and}
@item @code{||}
synonym for @code{or}
@item @code{"}
delimiter for string constants
@item @code{`}
delimiter for name substitution
@item @code{?}
synonym for @code{help}
@item @code{//}
comment delimiter.  Comment extends to end of line.
@item @code{;}
statement separator
@item @code{,}
separator for expression lists and function arguments
@item @code{\}
escape character for @code{"} and @code{\} within strings.  @xref{string expressions}.
@item @code{..}
interval specifier for intvecs (see @ref{intvec expressions}).
E.g. @code{1..3} which is equivalent to @code{1, 2, 3}.
@item @code{::}
access specifier within packages (complete name is package_name@code{::}identifier)
@item @code{_}
expression last printed.  @xref{Reuse of output}.
@item @code{~}
breakpoint in procedures.  @xref{Break points}.
@item @code{#}
list of parameters in procedures without explicit parameter list.
@xref{Parameter list}.
@item @code{@@}
is a letter.  Its use in identifiers is discouraged.
@item @code{$}
exits @sc{Singular}
@end table

@c ------------------------------------------------------------
@node Names and objects, Type conversion and casting, Special characters, The SINGULAR language
@subsection Names and objects
@cindex Names and objects

@sc{Singular} is a typed language.  This means that all names (=
identifiers) have to be declared prior to their use.
The general syntax of a declaration is

type name [ @code{=} expression ] @code{;}

where type stands for one of the data types of @sc{Singular},
name for the name of the object you are creating and expression
is any expression of the type or one that can be converted to the type
of the object (see @ref{Type conversion and casting}).
When expression is missing some default value is assigned whenever
possible.

For a complete list of types, refer to the @code{typeof} command
(@ref{typeof}).  To get information on the name and the object named by it, you
may use the @code{type} command (@ref{type}).

It is possible to redefine or overwrite an already existing object
(as an object of the same type).  A redefinition will
first set the variable to the default value and then compute the expression.
The difference between redefinition and overwriting is shown in the following
example:

@strong{Example:}
@example
@c example
  int i=3;
  i=i+1;        // overwriting
  i;
  int i=i+1;    // redefinition
  i;
@c example
@end example


Every object in @sc{Singular} has a type and a value.
In most cases it has also a name and in some cases an attribute list.

Each object of type
@code{poly},
@code{ideal},
@code{vector},
@code{module},
@code{map},
@code{matrix},
@code{number},
@code{resolution}
belongs to a specific ring.
Also @code{list}, if one of the objects belong to a ring.

These objects are local to the ring, hence their names can be used for other
objects in other rings. Objects from one ring can be mapped to another
ring with an object of type @code{map}
(or with the commands @code{fetch} or @code{imap}).

The other types do not belong to a ring and can be accessed within every ring.

Usually @sc{Singular} (i.e. if possible) gives an error message or
warning when the same name is defined again. However be sure not to use
the name of an object as a name for a ring variable and vice versa. This
may not be considered as an error, but the evaluation of the name may be
confusing.

The following names are predefined commands or variables
and cannot be used otherwise:

@c @code{alternating},
@code{and},
@code{attrib},
@code{bareiss},
@code{basering},
@code{break},
@code{char},
@code{char_series},
@code{charstr},
@code{cleardenom},
@code{close},
@code{continue},
@code{contract},
@code{coef},
@code{coeffs},
@code{dbprint},
@code{def},
@code{defined},
@code{deg},
@code{degBound},
@code{degree},
@code{delete},
@code{det},
@code{diff},
@code{dim},
@code{div},
@code{dring},
@code{dump},
@code{echo},
@code{else},
@code{eval},
@code{exit},
@code{execute},
@code{export},
@code{extgcd},
@code{facstd},
@code{factorize},
@code{fetch},
@code{fglm},
@code{find},
@code{finduni},
@code{for},
@code{forif},
@code{freemodule},
@code{gcd},
@code{gen},
@code{getdump},
@code{help},
@code{hilb},
@code{homog},
@code{ideal},
@code{if},
@code{imap},
@code{indepSet},
@code{insert},
@code{int},
@code{interred},
@code{intersect},
@code{intmat},
@code{intvec},
@code{jacob},
@code{jet},
@code{kbase},
@code{keepring},
@code{kill},
@code{killattrib},
@code{koszul},
@code{lead},
@code{leadcoef},
@code{leadexp},
@code{LIB},
@code{lift},
@code{liftstd},
@code{link},
@code{list},
@code{listvar},
@code{map},
@code{matrix},
@code{maxideal},
@code{memory},
@code{minbase},
@code{minor},
@code{minpoly},
@code{minres},
@code{mod},
@code{module},
@code{monitor},
@code{mres},
@code{mstd},
@code{mult},
@code{multBound},
@code{nameof},
@code{names},
@code{ncols},
@code{newline},
@code{NF},
@code{noether},
@c @code{NOT},
@code{not},
@code{npars},
@code{nrows},
@code{number},
@code{nvars},
@code{open},
@code{or},
@code{ord},
@code{ordstr},
@code{option},
@code{package},
@code{pagelength},
@code{pagewidth},
@code{par},
@code{parameter},
@code{pardeg},
@code{parstr},
@code{pause},
@code{poly},
@code{preimage},
@code{prime},
@code{print},
@code{printlevel},
@code{proc},
@code{prune},
@code{qhweight},
@code{qring},
@code{quit},
@code{quote},
@code{quotient},
@code{random},
@c @code{rank},
@code{read},
@code{reduce},
@code{regularity},
@code{res},
@code{reservedName},
@code{resolution},
@code{resultant},
@code{return},
@code{ring},
@code{rtimer},
@code{rvar},
@code{setring},
@code{short},
@code{simplify},
@code{size},
@code{sortvec},
@code{sres},
@code{status},
@code{std},
@code{string},
@code{subst},
@code{system},
@code{syz},
@code{test},
@code{timer},
@code{TRACE},
@code{trace},
@code{transpose},
@code{type},
@code{typeof},
@code{var},
@code{varstr},
@code{vdim},
@code{vector},
@code{verbose},
@code{voice},
@code{wedge},
@code{weight},
@code{while},
@code{whileif},
@code{write}.

You  get a list of the reserved names by @code{reservedName();},
see @ref{reservedName}.

User defined global names start with a letter and consist only of letters and
digits.
They must not coincide with reserved names (keywords) and should not interfere
with monomials. All names are case sensitive.
Indexed names are built as
name followed by @code{(} int_expression @code{)}.
A list of indexed names can be built as a name followed by
@code{(} int_expression @code{)}.
@example
@c example
  ring R;
  int n=3;
  ideal j(3);
  ideal j(n);     // is equivalent with the above
  ideal j(2)=x;
  j(2..3);
@c example
@end example

Hier fehlt noch was ueber die defs.

@c ------------------------------------------------------------
@node Type conversion and casting, Flow control, Names and objects, The SINGULAR language
@subsection Type conversion and casting
@cindex Type conversion
Assignments convert the type of an expression to the type
of the left-hand side of the assignment.
Operations, which require certain
types of operands can also implicitly convert the type of an
expression (e.g. you can multiply a polynomial by an integer because
the integer is automatically converted to polynomial).
Possible conversions are:
@* @sp 1
@enumerate
@item
@code{int} @expansion{} @code{poly}
@item
@code{int} @expansion{} @code{number}
@item
@code{number} @expansion{} @code{poly}
@item
@code{int} @expansion{} @code{vector}
(i @expansion{} i*gen(1))
@item
@code{poly} @expansion{} @code{vector}
(p @expansion{} p*gen(1))
@item
@code{int} @expansion{} @code{intvec}
@item
@code{intvec} @expansion{} @code{intmat}
@item
@code{matrix} @expansion{} @code{module}
@item
@code{vector} @expansion{} @code{module}
@item
@code{ideal} @expansion{} @code{module}
@item
@code{ideal} @expansion{} @code{matrix}
@item
@code{vector} @expansion{} @code{matrix}
@item
@code{module} @expansion{} @code{matrix}
@item
@code{intvec} @expansion{} @code{matrix}
@item
@code{intmat} @expansion{} @code{matrix}
@item
@code{string} @expansion{} @code{proc}
@item
@code{resolution} @expansion{} @code{list}
@item
@code{list} @expansion{} @code{resolution}.
@end enumerate

Note that type conversions do not act transitively.

@cindex Type casting
An expression can be casted to another type by using a type name
as a function returning this type.
Possible type castings are:
@enumerate
@item
to @code{string} from @code{int}, @code{number}, @code{poly}, @code{vector},
 @code{ideal}, @code{matrix}, @code{module}, @code{map}, @code{proc}
@item
to @code{int} from @code{number}, @code{poly}
@item
to @code{number} from @code{poly}
@item
to @code{poly} from @code{int}, @code{number}
@item
to @code{ideal} from @code{vector}, @code{poly},
@code{matrix}, @code{int}, @code{number}
@item
to @code{ideal} from expression lists of @code{poly},
@code{int}, @code{number}. (The list may be empty)
@item
to @code{ideal} from @code{matrix}, @code{vector}, @code{poly}, @code{module}
@item
to @code{matrix} from @code{module}, @code{ideal}, @code{vector}.
@* There are two forms to convert something to a matrix:
if @code{matrix(xx)} is used then the size of the matrix will
be determined by xx.
But @code{matrix(xx,a,b)} may also be used - the result is
an a x b matrix.
@item
to @code{intvec} from expression lists of @code{int}. (The list may be empty)
@item
to @code{module} from expression lists of @code{vector}
@code{int}, @code{number}, @code{poly}. (The list may be empty)
@item
to @code{module} from @code{matrix}, @code{vector}, @code{ideal}.
@item
to @code{list} from expression lists of any type. (The list may be empty)
@end enumerate
@strong{Examples:}
@example
@c example
  ring r=0,x,(c,dp);
  number(3x);
  number(poly(3));
  ideal i=1,2,3,4,5,6;
  print(matrix(i));
  print(matrix(i,3,2));
  vector v=[1,2];
  print(matrix(v));
  module(matrix(i,3,2));
@c example
@end example



@c ------------------------------------------------------------
@node Flow control, ,Type conversion and casting, The SINGULAR language
@subsection Flow control
@cindex Flow control
@cindex block

A block is a sequence of commands surrounded by @{ and @}.
@example
  @{
     command;
     @dots{}
  @}
@end example
Blocks are used whenever @sc{Singular} is used as a structured programming
language. The @code{if} and @code{else} structures allow conditional 
execution of blocks (See @ref{if}, @ref{else}). @code{for} and @code{while}
loops are available for repeated execution of blocks (See @ref{for}, 
@ref{while}).
In procedure definitions the main part and the example section are blocks
as well(See @ref{proc}).
@menu
* break::
* quit::
* keepring::
* export::
* if::
* else::
* for::
* while::
* proc::
* return::
* continue::
@end menu


@c ---------------------------------------------------------------------------
@node Procedures, Libraries, The SINGULAR language, General concepts
@section Procedures
@cindex Procedures
Procedures contain sequences of @sc{Singular} commands in a special format.
They are used to extend the set of commands with your own commands.
Procedures are defined by either typing them in on the command line or by
loading them from a file. If a procedure is defined in a file which complies
with the syntax rules for libraries, this file may be loaded with the
@code{LIB} command and the procedure may have additional sections (cf.
@ref{Proc in a library}).
Procedures are invoked like a normal built-in command, i.e. by typing their
name followed by the list of arguments
in parentheses. The invocation then executes
the sequence of commands stored in the specified procedure.

@menu
* Proc definition::
* Names in proc::
* Parameter list::
* Proc commands::
* Proc in a library::
* Loading of procedure files::
@end menu
@c -------------------------------------------------
@node Proc definition, Names in procedures, Procedures, Procedures
@subsection Proc in a library
@cindex Proc in a library
@table @code
@item @strong{Syntax:}
@code{[static] proc} proc_name [parameter_list]
@*["help_text"]
@*@code{@{}
@*
@tex
\quad
@end tex
   procedure_body
@*@code{@}}
@*[@code{example}
@*@code{@{}
@*
@tex
\quad
@end tex
   sequence_of_commands;
@*@code{@}}]
@item @strong{Purpose:}
defines a new function, the @code{proc} proc_name, with the additional 
information help_text, which is copied to the screen by 
@code{help proc_name;} and the @code{example} section
which is executed by @code{example proc_name;}. 

@* The help_text, the parameter_list, and the example section are optional.
The default for a parameter_list is @code{(list #)}, see @ref{Parameter list}.
The help and example sections are ignored if the procedure is defined 
interactively, i.e. if it was not loaded from a file by a @code{LIB} command.

@* Specifying static in front of the proc-definition (in a library file)
makes this procedure local to the library, i.e. accessible only for the other
procedures in the same library, but not for the users. So there is no
reason anymore to define a procedure within another one (it just makes
debugging harder). 

@item @strong{Example of a procedure:}
@example
@c example
  //
  // interactive definition of a procedure:
  //
  // The following procedure computes the Milnor number of a given
  // polynomial p, i.e. of the hypersurface singularity defined by p
  //
  proc milnor_number (poly p)
  "USAGE:    milnor_number(p);  p=poly
   RETURN:   Milnor number of the hypersurface singularity defined by p,
             resp. -1 if it is not isolated.
   EXAMPLE:  example milnor_number; shows an example."
  {
  //-----------------------computations----------------------------------
    ideal i= std(jacob(p));
    int m_nr=vdim(i);
  //-----------------------error message---------------------------------
    if (m_nr<0) { "// not an isolated singularity";}
  //-----------------------result----------------------------------------
    return(m_nr);         // the value of m_nr is returned
  }
  example 
  {
    "EXAMPLE:"; echo=2;
    ring r=0,(x,y),ds;
    poly p=x^2+y^4;
    milnor_number(p);
  };
  //
  // Use of this procedure
  //
  ring r1=0,(x,y,z),ds;
  poly p=x^2+y^2+z^5;
  milnor_number(p);
  //
  // help section is ignored, since the procedure was defined 
  // interactively
  //
  help milnor_number;
  //
  // example section is ignored for the same reason
  //
  example milnor_number;
@c example
@end example

@item @strong{Example of a static library procedure:}
@example
@c include sample.lib
@end example
@example
@c example
  //
  // load the library sample.lib
  //
  LIB "sample.lib";
  //
  // show an example
  //
  example tab;
  //
  // use the procedure tab
  //
  "*"+tab(3)+"*";
  //
  // the static procedure internal_tab is not accessible
  //
  "*"+internal_tab(3)+"*";
  //
  // show the help section for tab
  //
  help tab;
@c example
@c    " for(int n=0; n<=5; n=n+1)";
@c    " { tab(5-n)+\"*\"+tab(n)+\"+\"+tab(n)+\"*\"; }";
@end example

@*A convenient and recommended way to define procedures is to prepare a file
and read this file with the @code{LIB} command.
The differences between procedures from libraries and
other procedures are that the help and example part are ignored in 
interactive definitions and that static can only be specified in libraries.

@item @strong{Guidelines for the help section of a procedure:}
@* The help text of a procedure should contain information about the usage,
   purpose, return values and generated objects. Particular assumptions or 
   limitations should be listed. If global objects are generated, this should 
   be mentioned, too.

@*The libraries contained in the @sc{Singular} distribution use the following 
format for the help text:
@example
USAGE:    <proc_name>(<parameters>);   <explanation of parameters>
[CREATE:  <description of created objects which are not returned>]
RETURN:   <description of the purpose and return value>
[NOTE:    <paritcular assumptions or limitations, hints>]
EXAMPLE:  example <proc_name>; shows an example
@end example
@end table 

@menu
* LIB::
* Libraries::
* Procedures::
* Examples::
* Control structures::
* return::
@end menu

@c ---------------------------------------
@node Names in procedures, Parameter list, Proc definition, Procedures
@subsection Names in procedures
@cindex Names in procedures
@cindex local names

All variables are local to the procedure they are defined in.
These names cannot interfere with names in other
procedures and are automatically deleted after having executed
the proc.
Names can be made global by @code{export} (see @ref{export}).
These global names will not be deleted automatically.
Ring dependent variables are stored together with the ring and deleted
when the ring is deleted. You can 'move up' a ring by one nesting level
with @code{keepring} (see @ref{keepring}). All variables living in that
ring will be moved together with that ring.

@example
  proc xxx
  @{
    int k=4;        //defines a local variable k
    int result=k+2;
    export result;  //defines the global variable "result".
  @}
@end example

If you type @code{listvar(all);} after having executed a proc you will
see that the variable @code{result} is still there while @code{k}
has been deleted.

Often a procedure is started while a basering is active. The procedure then 
works in this basering without knowing its name. Therefore a name has to be
assigned to the basering before executing e.g. map commands. This is done by 
the assignment @code{def r=basering;}, writing @code{ring r=basering;} leads
to an error.

Internally, local variables are stored using the nesting level.
You will see the nesting level
if you do a @code{listvar()} command inside a proc(See @ref{listvar}).

@c ---------------------------------------
@node Parameter list, Procedure commands, Names in procedures, Procedures
@subsection Parameter list
@cindex Parameter list
@table @code
@item @strong{Syntax:}
@code{( )}
@*@code{(} parameter_definition @code{)}
@item @strong{Purpose:}
defines the number, type and names of the
arguments to a @code{proc}.
@*The parameter_list is optional.
The default for a parameter_list is @code{(list #)}
which means the arguments are referenced by @code{#[1], #[2]}, etc.
@item @strong{Example:}
@example
  proc x0
  @{
      // can be called with
  ... // any number of arguments of any type: #[1], #[2],...
      // number of arguments: size(#)
  @}

  proc x1 ()
  @{
  ... // can only be called without arguments
  @}

  proc x2 (ideal i, int j)
  @{
  ... // can only be called with 2 arguments,
      // which can be converted to ideal resp. int
  @}

  proc x3 (i,j)
  @{
  ... // can only be called with 2 arguments
      // of any type
  @}

  proc x5 (i,list #)
  @{
  ... // can only be called with more than 1 argument
      // number of arguments: size(#)+1
  @}

@end example
@item @strong{Notes:}
@* The parameter_list may stretch across multiple lines.
@* A parameter may have any type (including the types @code{proc}
   and @code{ring}). If a parameter is of type ring, then it
   can only be specified by name, but not with a type, e.g.
@example
   proc x6 (r)
   @{
   ... // this is correct even if the parameter is a ring
   @}

   proc x7 (ring r)
   @{
   ... // this is NOT CORRECT
   @}
@end example
@end table

@c --------------------------------------- ----------
@node Procedure commands, Loading of procedure files, Parameter list, Procedures
@subsection Procedure commands
@cindex Procedure commands
@menu
* export::
* keepring::
* return::
@end menu
@iftex
@table @code
@item export
see @ref{export}
@item keepring
see @ref{keepring}
@item return
see @ref{return}
@end table
@end iftex


@c ---------------------------------------
@node Loading of procedure files,  , Procedure commands, Procedures
@subsection Loading of procedure files
@cindex LIB
@cindex Loading of procedure files
Files containing @sc{Singular} procedures may be loaded in two ways
(the whole library will be loaded, the quotes "" are necessary):
@*@code{< "file_name";}       (if the library does not contain helptext
and examples) @*@code{LIB "file_name";}

To list all loaded procedures resp. libraries, type
@code{listvar(proc);} resp.
@code{LIB;}

To close a procedure type
@code{kill proc_name;}

If the libary does not contain an info string and a version string 
it can be loaded by @code{<"..."} because it contains valid @sc{Singular} 
commands. With @code{<} the whole file is read by @sc{Singular} and the 
body of the procedures is stored in the main memory. Help and example 
sections of the procedures are ignored. Any other text in the file is
executed. Problems may occur if one of the commands in the file is a
procedure call. These problems do not occur if all procedures are called
with the LIB command. Because of these limitations and problems the use of 
@code{<} is @strong{discouraged}.


@menu
* LIB command::
@end menu

@c ----------------------------------
@node LIB command, , Loading of procedure files, Loading of procedure files
@cindex LIB
@table @code
@item @strong{Syntax:}
@code{LIB} string_expression@code{;}
@item @strong{Purpose:}
reads a library of procedures (proc) from a file. If the given
filename does not start with @kbd{.} or @kbd{/}, the following directories ares
searched for the file: the current directory,
the directories given in the environment variable
@code{SINGULARPATH}@footnote{@code{SPATH} on MS-DOS},
@code{/usr/local/share/Singular}
Only procedure names of the library are loaded, the body of the proc
is read during the first call of this proc. This minimizes
the memory consumption by unused procedures.
@item @strong{Example:}
@example
  LIB "general.lib"; // the names of the procedures in the
                     // library "general.lib" are now known to SINGULAR
@end example
@end table
@menu
* LIB in a library::
* string expressions::
* proc::
* Libraries::
* SINGULAR libraries:: all standard libraries.
@end menu
@iftex
See @ref{LIB in a library}; @ref{proc}; @ref{Libraries};
@ref{string expressions}; @ref{SINGULAR libraries}.
@end iftex

@c ----------------------------------------------------------------------
@c ----------------------------------------------------------------------
@node Libraries, Debugging tools, Procedures, General concepts
@section Libraries
@cindex Libraries
A library is a collection of @sc{Singular} procedures in a file.
@*@sc{Singular} reads a library with the command @code{LIB}, general
information about the library is displayed by the command
@code{help lib_name}. After loading the library, its procedures can be used
like the built-in @sc{Singular} functions. To have the full functionality
of a built-in function (like checking of the type of parameters, automatic
loading of necessary other libraries, help pages etc.), libraries have to
comply with the syntax rules described below. The default location for
library files is @code{/usr/local/share/Singular};
or can be given by the environment variable
@code{SINGULARPATH}@footnote{@code{SPATH} on MS-DOS}. Users, who do not
intend to write their own libraries, may skip paragraphs @ref{Format of a
library} to @ref{A good example} without loosing any relevant information.

@menu
* Format of a library::
* LIB in a library::
* info::
* version::
* A good example::
@end menu

@c ---------------------------------------
@c @node loading, Format of a library, libraries, libraries
@c @subsection loading
@c @cindex LIB
@c @cindex loading
@c Files containing @sc{Singular} procedures may be loaded in two ways
@c (the whole library will be loaded, the quotes "" are necessary):
@c @*@code{< "file_name";}       (if the library does not contain helptext
@c and examples) @*@code{LIB "file_name";}
@c
@c To list all loaded procedures resp. libraries, type
@c @code{listvar(proc);} resp.
@c @code{LIB;}
@c
@c To close a procedure type
@c @code{kill proc_name;}
@c
@c If the libary does not contain helptext and examples it can be loaded by
@c @code{<"..."} because it contains valid Singular commands.
@c With @code{<} the whole file is read by Singular and the body of the
@c procedures is stored in the main memory. Any other text in the file is
@c executed. Problems may occur if one of the commands in the file is a
@c procedure call. These problems do not occur if all procedures are called
@c with the LIB command.
@c
@c @menu
@c * LIB command::
@c @end menu
@c
@c ----------------------------------
@c @node LIB command, , loading, loading
@c @subsubsection LIB
@c @cindex LIB
@c @table @code
@c @item @strong{Syntax:}
@c @code{LIB} string_expression@code{;}
@c @item @strong{Purpose:}
@c read a library of procedures (proc) from a file. If the given
@c filename does not start with @kbd{.} or @kbd{/}, the following directories ares
@c searched for the file: the current directory,
@c the directories given in the environment variable
@c @code{SINGULARPATH}@footnote{@code{SPATH} on MS-DOS},
@c @code{usr/local/share/Singular}
@c Only a directory of the library is loaded, the body of the proc
@c is read during the first call of this proc. This minimizes
@c the memory consumption by unused procedures.
@c @item @strong{Example:}
@c @example
@c   LIB "lib"; // the names of the procedures in the
@c              // file lib are now known to @sc{Singular}
@c @end example
@c @end table
@c @menu
@c * LIB in a library::
@c * string expressions::
@c * proc::
@c * procedures and Libraries::
@c * SINGULAR libraries:: all standard libraries.
@c @end menu
@c @iftex
@c See @ref{LIB in a library}; @ref{proc}; @ref{procedures and Libraries};
@c @ref{string expressions}; @ref{SINGULAR libraries}.
@c @end iftex

@c ---------------------------------------
@c @node Format of a library, LIB in a library, Libraries, Libraries
@node Format of a library, LIB in a library, Libraries, Libraries
@subsection Format of a library
@cindex Format of a library

A library file can contain comments, @code{LIB} commands, @code{proc} commands
and @code{proc} commands with @code{example} and @code{help} sections,
i.e. the following keywords are allowed:
@code{info},
@code{version},
@code{LIB},
@code{/* ... */},
@code{//},
@code{[static] proc}.
Anything else will not be recognized by the parser of @sc{Singular} and will lead
to an error message while loading the library.
If an error occurs, loading is aborted and an error message is returned,
specifying the type of error and the line where it was detected.

@table @code
@item @strong{Example of a library file:}
@example
@c include sample_lib0.lib
@c example
  LIB"sample_lib0.lib";     // load sample_lib0.lib
  help sample_lib0.lib;     // view its info string

  proc tt1=dummy1;          // assign new names to
  kill dummy1;              // the procedures
  proc tt2=dummy2;
  kill dummy2;

  listvar(proc);            // list all available procs
  tt1;                      // show information about tt1
  string(tt1);              // show the string tt1
  tt2(tt1,2,3);             // use tt2 and tt1
@c example
@end example
@end table

@table @code
@item @strong{Unrecognized character in a library:}
@example
@c include bad_lib0.lib
@c example
  LIB"bad_lib0";
@c example
@end example
@end table

@c ---------------------------------------
@node LIB in a library, info, Format of a library, Libraries
@subsection LIB in a library
@cindex LIB in a library
@cindex LIB
@table @code
@item @strong{Syntax:}
@code{LIB} string_constant @code{;}
@item @strong{Purpose:}
Loads the given library, if it is not already loaded. Makes the procedures
of that given library available to @code{Singular}.
If a library uses procedures from other libraries, theses should be
called by such a @code{LIB} command.
@item @strong{Example:}
@example
  LIB "matrix.lib";
@end example
@end table

@c ---------------------------------------
@node info, version, LIB in a library, Libraries
@subsection info
@cindex  info in a library
@table @code
@item @strong{Syntax:}
@code{info} = string_constant @code{;}
@item @strong{Purpose:}
defines the general help for the library. This text is displayed on
@code{help lib_name;}.
@item @strong{Example:}
@example
  info="
        This could be the general help of an library.
       Quote must be escaped with an \ such as \"
  ";
@end example
@item @strong{Note:}
In the info-string the characters \ and " must be preceded by a \ (escaped).
It is recommended that the info string is placed on the top of a
library file and contains general information about the library as well
as a listing of all procedures available to the users (with a one line
description of each procedure).
@end table

@c ---------------------------------------
@node version, A syntax example, info, Libraries
@subsection version
@cindex  version in a library
@table @code
@item @strong{Syntax:}
@code{version} = string_constant @code{;}
@item @strong{Purpose:}
defines the version number for the library. It is displayed when the
library is loaded.
@item @strong{Example:}
@example
  version="$I@comment
@comment !! Do not erase the @comment at the end of the previous line !!
@comment !! It prevents cvs to substitue the id string                !!
d: sample.lib,v 1.2 1998/05/07 singular Exp $";
  version="some version string";
@end example
@item @strong{Note:}
It is common practice to simply define the version string to be 
@code{"$I}@comment
@comment !! Do not erase the @comment at the end of the previous line !!
@comment !! It prevents cvs to substitue the id string                !!
@code{d:$"} and let a version control system expand it.
@end table

@c ---------------------------------------
@node A syntax example, ,version, Libraries
@subsection a syntax example
@cindex a syntax example
@cindex template

Although there are very few enforced rules on the format of a library,
we recommend that certain guidelines should be followed (which will make
debugging and understanding easier). An example probably explains it
best.

@c @table @code
@example
  // $I@comment
@comment !! Do not erase the @comment at the end of the previous line !!
@comment !! It prevents cvs to substitue the id string                !!
d: template.lib,v 1.2 1998/05/07 08:19:32 singular Exp $
  //
  //
  ///////////////////////////////////////////////////////////////////////////
  version="$I@comment
@comment !! Do not erase the @comment at the end of the previous line !!
@comment !! It prevents cvs to substitue the id string                !!
d: template.lib,v 1.2 1998/05/07 08:19:32 singular Exp $;
  info="
         LIBRARY: template.lib

     This is just an example of a library aimed at illustrating how
     a library should be written

   Author: The Singular Team <singular@@mathematik.uni-kl.de>
   last modified: 19.04.1998

   dummy1(i,j);   example procedure accessible for the user.
  ";

  ///////////////////////////////////////////////////////////////////////////
  // load other libraries that are required.

  LIB "general.lib";

  ///////////////////////////////////////////////////////////////////////////
  // section of public procedures
  proc dummy1(proc p,
            int i,
            int j)
  "USAGE:   dummy1(p, i,j); p proc, i,j int
  RETURN:  returns the result of p(i,j)
  EXMAPLE: example dummy1; shows examples"
        @{ return(p(j,k)); @}
  example
  @{ "EXAMPLE:"; echo=2;
    dummy1(dummy2, 2, 3);
  @}

  ///////////////////////////////////////////////////////////////////////////
  // Section of internal functions
  //
  static
  proc dummy2(int j, int k)
  @{ return(string(j)+\"+\"+string(k)+\"=\"+string(j+k)); @}

  ///////////////////////////////////////////////////////////////////////////
@end example

The libraries contained in the @sc{Singular} distribution follow additional
guidelines for the info string. These can be summarized in the following
synopsis:
@example
info="
      LIBRARY: <library_name> <one line description of the content>

      <procedure1>;     <one line description of the purpose>
      .
      .
      <procedureN>;     <one line description of the purpose>";
@end example
The purpose of these one line descriptions is not to give a short help
for the procedure, but to help the user decide what procedure might be 
the right one for the job. Details can then be found in the help of
each procedure. Therefore parameters may be omitted or abbreviated if
necessary.

@c @end table

@c ----------------------------------------------------------------------
@node Debugging tools,  , Libraries, General concepts
@section Debugging tools
@cindex Debugging tools

If you have written your own proc and, while calling that proc,
@sc{Singular} does not come back to the prompt, you probably forgot
a bracket or a @code{"}. The easiest way to leave the proc
is to type some brackets or @code{"} and then @code{<RETURN>;} .

@menu
* Tracing of procedures::       
* Break points::                
* Printing of data::            
* libparse::                    
@end menu

@c ---------------------------------------
@node Tracing of procedures, Break points, Debugging tools, Debugging tools
@subsection Tracing of procedures
Setting the @code{TRACE} variable to 1 (resp. 3) results in a listing of
the called procedures (resp. together with line numbers).
If @code{TRACE} is set to 4, @code{Singular}
displays each line before its interpretation and waits for the @code{<RETURN>}
key being pressed.
@menu
* TRACE var::
@end menu
@iftex
See @ref{TRACE var}.
@end iftex
@*@strong{Example:}
@example
@c example
  proc t1
  @{
    int i=2;
    while (i>0)
    @{ i=i-1; @}
  @}
  TRACE=3;
  t1();
@c example
@end example

@c ---------------------------------------
@node Break points, Printing of data, Tracing of procedures, Debugging tools
@subsection Break points
A break point can be put into a proc by inserting the command @code{~}.
If @code{Singular} reaches a break point it asks for lines of commands
(linelength must be less than 80 characters)
from the user. It returns to normal execution if given an empty line.
See @ref{~}.
@*@strong{Example:}
@example
  proc t
  @{
    int i=2;
    ~;
    return(i+1);
  @}
  t();
  @expansion{} -- break point in t --
  @expansion{} -- 0: called    from STDIN --
  @@i;
  @expansion{} 2
  @expansion{} -- break point in t --

  @expansion{} 3
@end example
@sp 2

@c ---------------------------------------
@node Printing of data,libparse,Break points,Debugging tools
@subsection Printing of data
The procedure @code{dbprint} is useful for optional output of data:
it takes 2 arguments and prints the second argument, if the first
argumet is positive, and does nothing otherwise.
@menu
* dbprint::
* voice::
@end menu
@iftex
See @ref{dbprint}; @ref{voice}.
@end iftex

@c ---------------------------------------
@node libparse,,Printing of data,Debugging tools
@subsection libparse
@cindex libparse

@sc{libparse} is a stand-alone program contained in the @sc{Singular} package,
which cannot be called inside of @sc{Singular}. It is a debugging tool for
libraries which performs exactly the same checks as the LIB command in
@sc{Singular}, but generates more output during parsing.
On a Unix platform it is executed
by the command @code{libparse} lib_name at the shell-prompt. It is useful,
if an error occurs while loading the library, but the whole block around the
line specified seems to be correct. In these situations the real error might
be hundreds of lines earlier in the library.

Command line options:
@table @asis
@item @code{-d} Debuglevel
increases the amount of output during parsing, where Debuglevel is an integer
between 0 and 4. Default is 0.
@item @code{-s}
turns on reporting about violations of unenforced syntax rules
@end table

The following syntax checks will be performed in any case:
@itemize @bullet
@item counting of pairs of brackets @{,@} , [,] and (,)
    (number of @{ has to match number of @}, same for [,] and (,) ).
@item counting of "
    ( number of " must be even ).
@item general library syntax
    ( only LIB, static, proc (with paramaters, help, body and example)
and comments, i.e // and '/* ... */' are allowed).
@end itemize
Its output lists all procedures that have been parsed successfully:

@strong{Example:}
@* $ @code{libparse general.lib}
@example
  Library        function     line,start-eod   line,body-eob    line,example-eoe
Version:(1.5,1998/04/03);
g general.lib         A_Z line  31, 1449-1474    37, 1774-2835    75, 2837-2996
g general.lib    binomial line  86, 3079-3115    94, 3560-4047   112, 4049-4195
g general.lib   factorial line 121, 4278-4308   127, 4566-4864   141, 4866-4982
g general.lib   fibonacci line 149, 5065-5095   156, 5436-5778   170, 5780-5886
g general.lib     kmemory line 178, 5969-5984   182, 6116-6225   186, 6227-6273
g general.lib     killall line 192, 6356-6369   203, 6935-7797   242, 7799-8219
g general.lib    number_e line 256, 8302-8323   264, 8665-9192   288, 9194-9297
g general.lib   number_pi line 297, 9380-9402   305, 9768-10976  358,10978-11083
g general.lib      primes line 367,11166-11192  373,11494-11729  380,11731-11814
g general.lib     product line 387,11897-11922  395,12379-12980  415,12982-13285
g general.lib ringweights line 432,13368-13388  441,13888-13999  446,14001-14204
g general.lib        sort line 457,14287-14309  490,16379-18246  562,18248-18812
g general.lib         sum line 581,18895-18916  589,19375-19966  608,19968-20299
g general.lib       which line 626,20382-20402  632,20644-21198  659,21200-21256
@end example

where the following abbreviations are used:
@itemize @bullet
@item g: global procedure (default)
@item l: static procedure, i.e. local to the library.
@end itemize

each of the following is the position of the byte in the library.
@itemize @bullet
@item start: begin of 'proc'
@item eod: end of parameters
@item body: start of procedurebody '@{'
@item eob:  end of procedurebody '@}'
@item example: position of 'example'
@item eoe: end of example '@}'
@end itemize

The following example shows the result of a missing close-barcket @} in
line 129 of the library @code{general.lib}.

@example
> LIB"./general.lib";
// ** loading ./general.lib... (1.5,1998/04/03)...done.
   ? Library ./general.lib: ERROR occured: in line 664, 21337.
   ? missing close bracket '@}' at end of library in line 664.
   ? Cannot load library,... aborting.
   ? error occurred in STDIN line 1: `LIB"./general.lib";`
>
@end example

@c Searching for the end of the
@c procedure @code{factorial} gives us line 146, but the parser is checking
@c everything until the bracketcounter @{-@} is zero. So every help-section
@c is checked. One of those as (,) in it.

@c The error is in line 129
@c @*@code{line 129:   if ( typeof(#[1])=="string" ) @{ number r=1; }
@c should be
@c @*@code{line 129:   if ( typeof(#[1])=="string" ) @{ number r=1; @}}
The error message specifies a missing @} in line 664. But the output of
libparse shows that the last properly recognized proc was
@code{binomial} starting at line 86. So the error must be in the next
proc  @code{factorial}.