===================================================================
RCS file: /home/cvs/OpenXM/src/asir-doc/parts/asir.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -p -r1.2 -r1.3
--- OpenXM/src/asir-doc/parts/asir.texi	1999/12/10 06:58:49	1.2
+++ OpenXM/src/asir-doc/parts/asir.texi	1999/12/21 02:47:31	1.3
@@ -1,35 +1,83 @@
+@comment $OpenXM$
+\BJP
 @node $B%f!<%68@8l(B Asir,,, Top
 @chapter $B%f!<%68@8l(B Asir
+\E
+\BEG
+@node User language Asir,,, Top
+@chapter User language @b{Asir}
+\E
 
 @noindent
+\BJP
 @b{Asir} $B$NAH$_9~$_H!?t$O(B, $B0x?tJ,2r(B, GCD $B$J$I$N7W;;$r9T$&$b$N(B, $B%U%!(B
 $B%$%kF~=PNO$r9T$&$b$N(B, $B$"$k$$$O?t<0$N0lIt$r<h$j=P$9$b$N$J$I$5$^$6$^$J$b$N(B
 $B$,MQ0U$5$l$F$$$k$,(B, $B%f!<%6$,<B:]$K9T$$$?$$$3$H$r<B9T$5$;$k$?$a$K$O0l(B
 $BHL$K$O%f!<%68@8l$K$h$k%W%m%0%i%`$r=q$/I,MW$,$"$k(B. $B%f!<%68@8l$b(B 
 @b{Asir} $B$H8F$P$l$k(B. $B0J2<$G$O(B, $B%f!<%68@8l$NJ8K!5,B'$*$h$S<B:]$N%f!<(B
 $B%68@8l%W%m%0%i%`$rNc$H$7$?%W%m%0%i%`$N=q$-J}$K$D$$$F=R$Y$k(B. 
+\E
+\BEG
+@b{Asir} provides many built-in functions, which perform algebraic
+computations, e.g., factorization and GCD computation, file I/O,
+extract a part of an algebraic expression, etc.
+In practice, you will often encounter a specific problem for which
+@b{Asir} does not provide a direct solution.  For such cases, you have
+to write a program in a certain user language.  The user language for
+@b{Asir} is also called @b{Asir}.  In the following, we describe the
+Syntax and then show how to write a user program by several examples.
+\E
 
 @menu
+\BJP
 * $BJ8K!(B (C $B8@8l$H$N0c$$(B)::
 * $B%f!<%6Dj5AH!?t$N=q$-J}(B::
+\E
+\BEG
+* Syntax (Difference from C language)::
+* Writing user defined functions::
+\E
 @end menu
 
 
+\BJP
 @node $BJ8K!(B (C $B8@8l$H$N0c$$(B),,, $B%f!<%68@8l(B Asir
 @section $BJ8K!(B (C $B8@8l$H$N0c$$(B)
+\E
+\BEG
+@node Syntax (Difference from C language),,, User language Asir
+@section Syntax --- Difference from C language
+\E
 
 @noindent
+\BJP
 @b{Asir} $B$NJ8K!$O(B C $B8@8l$K=`5r$7$F$$$k(B. 
 $B$*$b$JAj0cE@$O<!$NDL$j$G$"$k(B. $B0J2<$G(B, $BJQ?t$H$O(B @b{Asir} $B$K$*$1$k(B
 $B%W%m%0%i%`MQ$NJQ?t(B, $B$9$J$o$ABgJ8;z$G;O$^$kJ8;zNs$r0UL#$9$k$3$H$H$9$k(B. 
+\E
+\BEG
+The syntax of @b{Asir} is based on C language.
+Main differences are as follows.
+In this section, a variable does not mean an indeterminate, but
+a program variable which is written by a string which begins with a
+capital alphabetical letter in @b{Asir}.
+\E
 
 @itemize @bullet
 @item
-$BJQ?t$N7?$,$J$$(B. 
+\JP $BJQ?t$N7?$,$J$$(B. 
+\EG No types for variables.
 
+\BJP
 $B4{$K@bL@$7$?$H$*$j(B, @b{Asir} $B$G07$o$l$kBP>]<+?H$OA4$F2?$i$+$N7?(B
 $B$r;}$C$F$$$k(B. $B$7$+$7(B, $B%W%m%0%i%`JQ?t<+BN$O(B, $B$I$N$h$&$JBP>]$G$b(B
 $BBeF~$G$-$k$H$$$&0UL#$G7?$,$J$$$N$G$"$k(B. 
+\E
+\BEG
+As is already mentioned, any object in @b{Asir} has their respective
+types.  A program variable, however, is type-less, that is, any typed
+object can be assigned to it.
+\E
 
 @example
 [0] A = 1;
@@ -43,21 +91,51 @@
 @end example
 
 @item
+\BJP
 $BH!?tFb$NJQ?t$O(B, $B%G%U%)%k%H$G$O2>0z?t$r$3$a$F$9$Y$F6I=jJQ?t(B. 
-$B$?$@$7(B, @code{extern} $B@k8@$5$l$?JQ?t$O(B, $B%H%C%W%l%Y%k$K$*$1$kBg0hJQ?t$H$J$k(B. 
 
+$B$?$@$7(B, @code{extern} $B@k8@$5$l$?JQ?t$O(B, $B%H%C%W%l%Y%k$K$*$1$kBg0hJQ?t$H$J$k(B. 
 $B$9$J$o$A(B, $BJQ?t$N%9%3!<%W$OBg0hJQ?t$H6I=jJQ?t$N(B 2 $B<oN`$KC1=c2=$5$l$F$$$k(B. 
 $B%H%C%W%l%Y%k(B, $B$9$J$o$A%W%m%s%W%H$KBP$7$FF~NO$5$l$?JQ?t$OA4$FBg0hJQ?t(B
 $B$H$7$FEPO?$5$l$k(B. $B$^$?H!?tFb$G$O<!$N$$$:$l$+$H$J$k(B. 
+\E
+\BEG
+Variables, together with formal parameters, in a function (procedure)
+are all local to the function by default.
 
+Variables can be global at the top level,
+if they are declared with the key word @code{extern}.
+Thus, the scope rule of @b{Asir} is very simple.
+There are only two types of variables: global variables and local
+variables.
+A name that is input to the @b{Asir}'s prompt at the top level
+is denotes a global variable commonly accessed at the top level.
+In a function (procedure) the following rules are applied.
+\E
+
 @enumerate
 @item
+\BJP
 $BH!?t$,Dj5A$5$l$k%U%!%$%k$K$*$$$F(B, $B$=$NH!?tDj5A0JA0$K(B, $B$"$k(B
 $BJQ?t$,(B @code{extern} $B@k8@$5$l$F$$$k>l9g(B, $BH!?tFb$N$=$NJQ?t$bBg0hJQ?t(B
 $B$H$7$F07$o$l$k(B.
+\E
+\BEG
+If a variable is declared as global by an @code{extern} statement in
+a function, the variable used in that function denotes a global variable
+at the top level.
+Furthermore, if a variable in a function is preceded by an @code{extern}
+declaration outside the function but in a file where the function is
+defined, all the appearance of that variable in the same file denote
+commonly a global variable at the top level.
+\E
 
 @item
-@code{extern} $B@k8@$5$l$F$$$J$$JQ?t$O$=$NH!?t$K6I=jE*$H$J$k(B. 
+\JP @code{extern} $B@k8@$5$l$F$$$J$$JQ?t$O$=$NH!?t$K6I=jE*$H$J$k(B. 
+\BEG
+A variable in a function is local to that function, if it is not declared
+as global by an @code{extern} declaration.
+\E
 @end enumerate
 
 @example
@@ -77,48 +155,97 @@ end$
 @end example
 
 @item
-$B%W%m%0%i%`JQ?t$OBgJ8;z$G;O$^$j(B, $BITDj85(B, $BH!?t$O>.J8;z$G;O$^$k(B. 
+\JP $B%W%m%0%i%`JQ?t$OBgJ8;z$G;O$^$j(B, $BITDj85(B, $BH!?t$O>.J8;z$G;O$^$k(B. 
+\EG Program variables and algebraic indeterminates are distinguished in @b{Asir}.
 
+\BJP
 $B$3$NE@$O(B, $B4{B8$N?t<0=hM}%7%9%F%`$N$[$H$s$I$H0[$J$kE@$G$"$k(B. @b{Asir}
 $B$,$3$N;EMM$r:NMQ$7$?$N$O(B, $B%f!<%6$,ITDj85$N$D$b$j$G;HMQ$7$?JQ?t$K(B
 $B$J$s$i$+$NCM$,BeF~$5$l$F$$$?>l9g$K:.Mp$r>7$/(B, $B$H$$$&(B, $B4{B8$N(B
 $B%7%9%F%`$K$"$j$,$A$J>u67$rHr$1$k$?$a$G$"$k(B. 
+\E
+\BEG
+The names of program variables must begin with a capital letter;
+while the names of indeterminates and functions must begin with
+a small letter.
+      
+This is an unique point that differs from almost all other existing
+computer algebra systems.  The distinction between program variables
+and indeterminates is adopted to avoid the possible and usual confusion
+that may arise in a situation where a name is used as an indeterminate
+but, as it was, the name has been already assigned some value.
+To use different type of letters, capital and small, was a matter of
+syntactical convention like Prolog, but it is convenient to distinguish
+variables and indeterminates in a program.
+\E
 
 @item
-@code{switch} $BJ8(B, @code{goto} $B$,$J$$(B. 
+\JP @code{switch} $BJ8(B, @code{goto} $B$,$J$$(B. 
+\EG No @code{switch} statements, and @code{goto} statements.
 
-@code{goto} $B$,$J$$$?$a(B, $BB?=E%k!<%W$r0lEY$KH4$1$k$N$,$d$dJ#;($K$J$k>l9g$,$"$k(B. 
+\JP @code{goto} $B$,$J$$$?$a(B, $BB?=E%k!<%W$r0lEY$KH4$1$k$N$,$d$dJ#;($K$J$k>l9g$,$"$k(B. 
+\EG Lack of @code{goto} statement makes it rather bothering to exit from within multiple loops.
 
 @item
-$B%3%s%^<0$O(B, @code{for (A;B;C)} $B$^$?$O(B, @code{while(A)} $B$N(B @code{A}, @code{B}, @code{C} $B$K$N$_;H$&$3$H$,$G$-$k(B. 
+\BJP
+$B%3%s%^<0$O(B, @code{for (A;B;C)} $B$^$?$O(B, @code{while(A)} $B$N(B @code{A},
+@code{B}, @code{C} $B$K$N$_;H$&$3$H$,$G$-$k(B.
+\E
+\BEG
+Comma expressions are allowed only in @code{A}, @code{B} and @code{C}
+of the constructs @code{for (A;B;C)} or @code{while(A)}.
+\E
 
-$B$3$l$O(B, $B%j%9%H$r@5<0$J%*%V%8%'%/%H$H$7$F2C$($?$3$H$K$h$k(B. 
+\JP $B$3$l$O(B, $B%j%9%H$r@5<0$J%*%V%8%'%/%H$H$7$F2C$($?$3$H$K$h$k(B. 
+\EG This limitation came from adopting lists as legal data objects for @b{Asir}.
 
 @end itemize
 
 @noindent
-$B0J>e$O@)8B$G$"$k$,(B, $B3HD%$H$7$F$O<!$NE@$,5s$2$i$l$k(B. 
+\JP $B0J>e$O@)8B$G$"$k$,(B, $B3HD%$H$7$F$O<!$NE@$,5s$2$i$l$k(B. 
+\EG The above are limitations; extensions are listed as follows.
 
 @itemize @bullet
 @item
-$BM-M}<0$KBP$9$k7W;;$r(B, $BDL>o$N(B C $B$K$*$1$k7W;;$HF1MM$K$G$-$k(B. 
+\JP $BM-M}<0$KBP$9$k7W;;$r(B, $BDL>o$N(B C $B$K$*$1$k7W;;$HF1MM$K$G$-$k(B. 
+\BEG
+Arithmetic for rational expressions can be done in the
+same manner as is done for numbers in C language.
+\E
 
 @item
-$B%j%9%H$,07$($k(B. 
+\JP $B%j%9%H$,07$($k(B. 
+\EG Lists are available for data objects.
 
+\BJP
 $B9=B$BN$rMQ$$$k$^$G$b$J$$MWAG$N=89gBN$r(B, $B%j%9%H$GI=$9$3$H$,$G$-(B, 
 C $B$GD>@\=q$/>l9g$KHf3S$7$F%W%m%0%i%`$,C;$/(B, $BFI$_$d$9$/=q$1$k(B. 
+\E
+\BEG
+Lists are conveniently used to represent a certain collection of objects.
+Use of lists enables to write programs more easily, shorter and more
+comprehensible than use of structure like C programs.
+\E
 
 @item
-$B%f!<%6Dj5AH!?t$K$*$1$k%*%W%7%g%s;XDj(B. 
+\JP $B%f!<%6Dj5AH!?t$K$*$1$k%*%W%7%g%s;XDj(B. 
+\EG Options can be specified in calling user defined functions.
 
-$B$3$l$K4X$7$F$O(B, @xref{$B%*%W%7%g%s;XDj(B}.
+\JP $B$3$l$K4X$7$F$O(B, @xref{$B%*%W%7%g%s;XDj(B}.
+\EG @xref{option}.
 @end itemize
 
+\BJP
 @node $B%f!<%6Dj5AH!?t$N=q$-J}(B,,, $B%f!<%68@8l(B Asir
 @section $B%f!<%6Dj5AH!?t$N=q$-J}(B
+\E
+\BEG
+@node Writing user defined functions,,, User language Asir
+@section Writing user defined functions
+\E
 
 @menu
+\BJP
 * $B%f!<%6Dj5AH!?t(B::
 * $BJQ?t$*$h$SITDj85(B::
 * $B0z?t(B::
@@ -130,27 +257,67 @@ C $B$GD>@\=q$/>l9g$KHf3S$7$F%W%m%0%i%`$,C;$/(B, $BF
 * $B$5$^$6$^$J<0(B::
 * $B%W%j%W%m%;%C%5(B::
 * $B%*%W%7%g%s;XDj(B::
+\E
+\BEG
+* User defined functions::
+* variables and indeterminates::
+* parameters and arguments::
+* comments::
+* statements::
+* return statement::
+* if statement::
+* loop break return continue::
+* various expressions::
+* preprocessor::
+* option::
+\E
 @end menu
 
+\BJP
 @node $B%f!<%6Dj5AH!?t(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B%f!<%6Dj5AH!?t(B
+\E
+\BEG
+@node User defined functions,,, Writing user defined functions
+@subsection User defined functions
+\E
 
 @noindent
+\BJP
 $B%f!<%6$K$h$kH!?t$NDj5A$O(B @samp{def} $BJ8$G9T$&(B. $BJ8K!%(%i!<$OFI$_9~$_;~$K(B
 $B$"$kDxEY%A%'%C%/$5$l(B, $B$*$*$h$=$N>l=j$,I=<($5$l$k(B. 
 $B4{$K(B($B0z?t$N8D?t$K4X78$J$/(B)$BF1L>$NH!?t$,Dj5A$5$l$F$$$k>l9g$K$O(B, 
 $B$=$NH!?t$O:FDj5A$5$l$k(B. @code{ctrl()} $BH!?t$K$h$j(B @code{verbose} $B%U%i%0(B
 $B$,(B on $B$K$J$C$F$$$k>l9g(B, 
+\E
+\BEG
+To define functions by an user himself, @samp{def} statement must be used.
+Syntactical errors are detected in the parsing phase
+of @b{Asir}, and notified with an indication of where @b{Asir} found the error.
+If a function with the same name is already defined (regardless to
+its arity,) the new definition will override the old one, and the user
+will be told by a message,
+\E
 
 @example
 afo() redefined.
 @end example
 
 @noindent
+\BJP
 $B$H$$$&%a%C%;!<%8$,I=<($5$l$k(B. $B$"$kH!?t$NDj5A$K$*$$$F(B, $B$^$@L$Dj5A$NH!?t(B
 $B$r8F$S=P$7$F$$$F$b(B, $BDj5A;~$K$O%(%i!<$K$J$i$J$$(B. $B<B9T;~$KL$Dj5A$NH!?t(B
 $B$r8F$S=P$=$&$H$7$?>l9g$K%(%i!<$H$J$k(B. 
-
+\E
+\BEG
+on the screen when a flag @code{verbose} is set to a non-zero value by
+@code{ctrl()}.
+Recursive definition, and of course, recursive use of functions are
+available.
+A call for an yet undefined function in a function definition is not
+detected as an error.  An error will be detected at execution of the
+call of that yet undefined function.
+\E
 @example
 @tex
 /* $X!$ */
@@ -164,7 +331,8 @@ def f(X) @{ 
 @}
 
 @tex
-/* ${_i}C_j ( 0 \le i \le N, 0 \le j \le i )$ */
+\JP /* ${_i}C_j ( 0 \le i \le N, 0 \le j \le i )$ */
+\EG /* ${_i}C_j ( 0 \le i \le N, 0 \le j \le i )$ */
 @end tex
 
 def c(N)
@@ -180,8 +348,15 @@ def c(N)
 @end example
 
 @noindent
+\BJP
 2 $B$DL\$NNc$G$O(B, $BD9$5(B @code{N+1} $B$N%Y%/%H%k(B (@code{A}$B$H$9$k(B) $B$,JV$5$l$k(B. 
 @code{A[I]} $B$OD9$5(B @code{I+1} $B$NG[Ns$G$"$j(B, $B$=$N$=$l$>$l$NMWAG$,(B
+\E
+\BEG
+In the second example, @code{c(N)} returns a vector, say @code{A}, of length
+@code{N+1}.  @code{A[I]} is a vector of length @code{I+1}, and
+each element is again a vector which contains
+\E
 @iftex
 @tex
 ${_I}C_J$
@@ -190,28 +365,63 @@ ${_I}C_J$
 @ifinfo
 ICJ
 @end ifinfo
-$B$rMWAG$H$9$kG[Ns$G$"$k(B. 
+\JP $B$rMWAG$H$9$kG[Ns$G$"$k(B. 
+\EG as its elements.
 
 @noindent
+\BJP
 $B0J2<$G$O(B, C $B$K$h$k%W%m%0%i%_%s%0$N7P83$,$J$$?M$N$?$a$K(B, @b{Asir} $B8@8l(B
 $B$K$h$k%W%m%0%i%`$N=q$-J}$r2r@b$9$k(B. 
+\E
+\BEG
+In the following, the manner of writing @b{Asir} programs is exhibited
+for those who have no experience in writing C programs.
+\E
 
+\BJP
 @node $BJQ?t$*$h$SITDj85(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $BJQ?t$*$h$SITDj85(B
+\E
 
 @noindent
+\BJP
 $B4{$K=R$Y$?DL$j(B, @b{Asir} $B$K$*$$$F$O%W%m%0%i%`JQ?t$HITDj85$rL@3N$K(B
 $B6hJL$7$F$$$k(B. 
+\E
+\BEG
+@node variables and indeterminates,,, Writing user defined functions
+@subsection variables and indeterminates
+\E
 
 @table @b
+\BJP
 @item $BJQ?t(B
 $BBgJ8;z$G;O$^$j(B, $B%"%k%U%!%Y%C%H(B, $B?t;z(B, @samp{_} $B$+$i$J$kJ8;zNs(B
+\E
+\BEG
+@item variables (program variables)
+A program variable is a string that begins with a capital
+alphabetical letter followed by any numbers of alphabetical letters,
+digits and @samp{_}.
+\E
 
+\BJP
 $BJQ?t$"$k$$$O%W%m%0%i%`JQ?t$H$O(B, @b{Asir} $B$N$5$^$6$^$J7?$NFbIt7A<0$r(B
 $B3JG<$9$k$?$a$NH"$G$"$j(B, $B3JG<$5$l$?FbIt7A<0$,(B, $B$3$NJQ?t$NCM$G$"$k(B.  $BJQ(B
 $B?t$,<0$NMWAG$H$7$FI>2A$5$l$k;~$O(B, $B$=$3$K<}$a$i$l$?CM$KCV$-49$($i$l$k(B. 
 $B$9$J$o$A(B, $BFbIt7A<0$NCf$K$O%W%m%0%i%`JQ?t$O8=$l$J$$(B. $BJQ?t$OA4$F(B 0 $B$G(B
 $B=i4|2=$5$l$F$$$k(B. 
+\E
+\BEG
+A program variable is thought of a box (a carrier) which can contain
+@b{Asir} objects of various types.  The content is called the `value'
+of that variable.  When an expression in a program is to be evaluated,
+the variable appearing in the expression is first replaced by its value
+and then the expression is evaluated to some value and stored in
+the memory.  Thus, no program variable appears in objects in the
+internal form.
+All the program variables are initialized to the value 0.
+\E
 
 @example
 [0] X^2+X+1;
@@ -222,12 +432,23 @@ ICJ
 7
 @end example
 
+\BJP
 @item $BITDj85(B
 $B>.J8;z$G;O$^$j(B, $B%"%k%U%!%Y%C%H(B, $B?t;z(B, @samp{_} $B$+$i$J$kJ8;zNs(B
 
 $BITDj85$H$O(B, $BB?9`<04D$r9=@.$9$k:]$KE:2C$5$l$kJQ?t$r$$$&(B. @b{Asir} $B$K(B
 $B$*$$$F$O(B, $BITDj85$OCM$r$b$?$J$$D61[E*$J85$G$"$j(B, $BITDj85$X$NCM$NBeF~$O(B
 $B5v$5$l$J$$(B. 
+\E
+\BEG
+@item indeterminates
+An indeterminate is a string that begins with a small alphabetical letter
+followed by any numbers of alphabetical letters, digits and @samp{_}.
+      
+An indeterminate is a transcendental element, so-called variable,
+which is used to construct polynomial rings.
+An indeterminate cannot have any value.  No assignment is allowed to it.
+\E
 
 @example
 [3] X=x;
@@ -237,8 +458,14 @@ x^2+x+1
 @end example
 @end table
 
+\BJP
 @node $B0z?t(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B0z?t(B
+\E
+\BEG
+@node parameters and arguments,,, Writing user defined functions
+@subsection parameters and arguments
+\E
 
 @example
 def sum(N) @{
@@ -249,6 +476,7 @@ def sum(N) @{
 @end example
 
 @noindent
+\BJP
 $B$3$l$O(B, 1 $B$+$i(B @code{N} $B$^$G$N<+A3?t$NOB$r5a$a$kH!?t(B @code{sum()} $B$N(B
 $BDj5A$G$"$k(B. $B$3$NNc$K$*$1$k(B @code{sum(N)} $B$N(B @code{N} $B$,0z?t$G$"$k(B. 
 $B$3$NNc$O(B, 1 $B0z?tH!?t$NNc$G$"$k$,(B, $B0lHL$K0z?t$N8D?t$OG$0U$G$"$j(B, 
@@ -258,6 +486,36 @@ def sum(N) @{
 $B9TNs$r0z?t$KEO$7$?>l9g$G$"$k(B. $B$3$N>l9g$b(B, $BEO$5$l$?JQ?t$=$N$b$N$r=q$-(B
 $BBX$($k$3$H$O(B, $B$=$NH!?t$K6I=jE*$JA`:n$G$"$k$,(B, $BMWAG$r=q$-49$($?>l9g(B, 
 $B$=$l$O(B, $B8F$S=P$7B&$N%Y%/%H%k(B, $B9TNs$NMWAG$r=q$-49$($k$3$H$K$J$k(B. 
+\E
+\BEG
+This is an example definition of a function that sums up integers
+from 1 to @code{N}.  The @code{N} in @code{sum(N)} is called the
+(formal) parameter of @code{sum(N)}.
+The example shows a function of the single argument.
+In general, any number of parameters can be specified by separating
+by commas (@samp{,}).
+A (formal) parameter accepts a value given as an argument (or an actual
+parameter) at a function call of the function.
+Since the value of the argument is given to the formal parameter,
+any modification to the parameter does not usually affect the argument
+(or actual parameter).  However, there are a few exceptions: vector
+arguments and matrix arguments.
+      
+Let @code{A} be a program variable and assigned to a vector value
+@code{[ a, b ]}.
+If A is given as an actual parameter to a formal parameter, say @code{V},
+of a function, then an assignment in the function to the vector element
+designator @code{V[1]}, say @code{V[1]=c;}, causes modification of the
+actual parameter @code{A} resulting @code{A} to have an altered value
+@code{[ a c ]}.  Thus, if a vector is given to a formal parameter of
+a function, then its element (and subsequently the vector itself) in
+the calling side is modified through modification of the formal parameter
+by a vector element designator in the called function.
+The same applies to a matrix argument.
+Note that, even in such case where a vector (or a matrix) is given to
+a formal parameter, the assignment to the whole parameter itself has
+only a local effect within the function.
+\E
 
 @example
 def clear_vector(M) @{
@@ -269,16 +527,38 @@ def clear_vector(M) @{
 @end example
 
 @noindent
+\BJP
 $B$3$NH!?t$O(B, $B0z?t$N%Y%/%H%k$r(B 0 $B%Y%/%H%k$K=i4|2=$9$k$?$a$NH!?t$G$"$k(B. 
 $B$^$?(B, $B%Y%/%H%k$r0z?t$KEO$9$3$H$K$h$j(B, $BJ#?t$N7k2L$r0z?t$N%Y%/%H%k$K(B
 $B<}G<$7$FJV$9$3$H$,$G$-$k(B. $B<B:]$K$O(B, $B$3$N$h$&$J>l9g$K$O(B, $B7k2L$r%j%9%H(B
 $B$K$7$FJV$9$3$H$b$G$-$k(B. $B>u67$K1~$8$F;H$$$o$1$9$k$3$H$,K>$^$7$$(B. 
+\E
+\BEG
+This function will clear off the vector given as its argument to the
+formal parameter @code{M} and return a 0 vector.
+      
+Passing a vector as an argument to a function enables returning
+multiple results by packing each result in a vector element.
+Another alternative to return multiple results is to use a list.
+Which to use depends on cases.
+\E
 
+\BJP
 @node $B%3%a%s%H(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B%3%a%s%H(B
+\E
+\BEG
+@node comments,,, Writing user defined functions
+@subsection comments
+\E
 
 @noindent
-C $B$HF1MM(B @samp{/*} $B$H(B @samp{*/} $B$G0O$^$l$?ItJ,$O%3%a%s%H$H$7$F07$o$l$k(B. 
+\JP C $B$HF1MM(B @samp{/*} $B$H(B @samp{*/} $B$G0O$^$l$?ItJ,$O%3%a%s%H$H$7$F07$o$l$k(B. 
+\BEG
+The text enclosed by @samp{/*} and @samp{*/} (containing @samp{/*} and
+@samp{*/}) is treated as a comment and has no effect to the program
+execution as in C programs.
+\E
 
 @example
 /*
@@ -289,11 +569,22 @@ def afo(X) @{
 @end example
 
 @noindent
+\BJP
 $B%3%a%s%H$OJ#?t9T$KEO$C$F$b9=$o$J$$$,(B, $BF~$l;R$K$9$k$3$H$O$G$-$J$$(B. 
 @samp{/*} $B$,$$$/$D$"$C$F$b:G=i$N$b$N$N$_$,M-8z$H$J$j(B, $B:G=i$K8=$l$?(B 
 @samp{*/} $B$G%3%a%s%H$O=*N;$7$?$H8+$J$5$l$k(B. $B%W%m%0%i%`$J$I$G(B, $B%3%a%s%H(B
 $B$r4^$`2DG=@-$,$"$kItJ,$r%3%a%s%H%"%&%H$7$?>l9g$K$O(B, @code{#if 0},
 @code{#endif}$B$r;H$($P$h$$(B. (@xref{$B%W%j%W%m%;%C%5(B})
+\E
+\BEG
+A comment can span to several lines, but it cannot be nested.
+Only the first @samp{/*} is effective no matter how many @samp{/*}'s
+in the subsequent text exist, and the comment terminates at the first
+@samp{*/}.
+      
+In order to comment out a program part that may contain comments in it,
+use the pair, @code{#if 0} and @code{#endif}. (@xref{preprocessor})
+\E
 
 @example
 #if 0
@@ -303,10 +594,17 @@ def bfo(X) @{
 #endif
 @end example
 
+\BJP
 @node $BJ8(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $BJ8(B
+\E
+\BEG
+@node statements,,, Writing user defined functions
+@subsection statements
+\E
 
 @noindent
+\BJP
 @b{Asir} $B$N%f!<%6H!?t$O(B, 
 
 @example
@@ -316,18 +614,40 @@ def $BL>A0(B($B0z?t(B,$B0z?t(B,...,$B0z?t(B) @
     ...
     $BJ8(B
 @}
+\E
+\BEG
+An user function of @b{Asir} is defined in the following form.
+      
+@example
+def name(parameter, parameter,...,parameter) @{
+    statement
+    statement
+    ...
+    statement
+@}    
+\E
 @end example
 
 @noindent
+\BJP
 $B$H$$$&7A$GDj5A$5$l$k(B. $B$3$N$h$&$K(B, $BJ8$OH!?t$N4pK\E*9=@.MWAG$G$"$j(B, $B%W%m(B
 $B%0%i%`$r=q$/$?$a$K$O(B, $BJ8$,$I$N$h$&$J$b$N$G$"$k$+CN$i$J$1$l$P$J$i$J$$(B. 
 $B:G$bC1=c$JJ8$H$7$F(B, $BC1J8$,$"$k(B. $B$3$l$O(B, 
+\E
+\BEG
+As you can see, the statement is a fundamental element of the
+function.
+Therefore, in order to write a program, you have to learn what
+the statement is.  The simplest statement is the simple statement.
+One example is an expression with a terminator (@samp{;} or @samp{$}.)
+\E
 
 @example
 S = sum(N);
 @end example
 
 @noindent
+\BJP
 $B$N$h$&$K(B, $B<0$K=*C<5-9f(B (@samp{;} $B$^$?$O(B @samp{$}) $B$r$D$1$?$b$N$G$"$k(B. 
 $B$3$NC1J85Z$SN`;w$N(B @code{return} $BJ8(B, @code{break} $BJ8$J$I$,J8$N:G>.9=@.(B
 $BC10L$H$J$k(B. @code{if} $BJ8$d(B @code{for} $BJ8$NDj5A(B (@xref{$BJ8K!$N>\:Y(B}) $B$r8+$l(B
@@ -335,6 +655,18 @@ S = sum(N);
 $B$O(B, $BK\BN$K$OJ#?t$NJ8$,=q$1$k$3$H$,I,MW$H$J$k(B.  $B$3$N$h$&$J>l9g(B,
 @samp{@{} $B$H(B @samp{@}} $B$GJ8$NJB$S$r3g$C$F(B, $B0l$D$NJ8$H$7$F07$&$3$H$,$G(B
 $B$-$k(B. $B$3$l$rJ#J8$H8F$V(B.
+\E
+\BEG
+A `@code{return} statement' and `@code{break} statement' are also
+primitives to construct `statements.'
+As you can see the syntactic definition of `@code{if} statement' and
+`@code{for} statement', each of their bodies consists of a single
+`statement.'  Usually, you need several statements in such a body.
+To solve this contradictory requirement, you may use the `compound
+statement.'  A `compound statement' is a sequence of `statement's
+enclosed by a left brace @samp{@{} and a right brace @samp{@}}.
+Thus, you can use multiple statement as if it were a single statement.
+\E
 
 @example
 if ( I == 0 ) @{
@@ -345,261 +677,519 @@ if ( I == 0 ) @{
 @end example
 
 @noindent
+\BJP
 @samp{@}} $B$N8e$m$K$O=*C<5-9f$OI,MW$J$$(B. $B$J$<$J$i(B, @samp{@{} $BJ8JB$S(B 
 @samp{@}}$B$,4{$KJ8$H$J$C$F$$$F(B, @code{if} $BJ8$NMW@A$rK~$?$7$F$$$k$+$i$G(B
 $B$"$k(B. 
+\E
+\BEG
+No terminator symbol is necessary after @samp{@}},
+because @samp{@{} statement sequence @samp{@}} already forms a statement,
+and it satisfies the syntactical requirement of the
+`@code{if} statement.'
+\E
 
+\BJP
 @node return $BJ8(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection @code{return} $BJ8(B
+\E
+\BEG
+@node return statement,,, Writing user defined functions
+@subsection @code{return} statement
+\E
 
 @noindent
-@code{return} $BJ8$O(B, 
+\JP @code{return} $BJ8$O(B, 
+\EG There are two forms of @code{return} statement.
 
 @example
-return $B<0(B;
+\JP return $B<0(B;
+\EG return expression;
 
 return;
 @end example
 
 @noindent
+\BJP
 $B$N(B 2 $B$D$N7A<0$,$"$k(B. $B$$$:$l$bH!?t$+$iH4$1$k$?$a$NJ8$G$"$k(B. $BA0<T$O(B
 $BH!?t$NCM$H$7$F(B $B<0(B $B$rJV$9(B. $B8e<T$G$O(B, $BH!?t$NCM$H$7$F2?$,JV$5$l$k$+(B
 $B$O$o$+$i$J$$(B. 
+\E
+\BEG
+Both forms are used for exiting from a function.
+The former returns the value of the expression as a function value.
+The function value of the latter is not defined.
+\E
 
+\BJP
 @node if $BJ8(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection @code{if} $BJ8(B
+\E
+\BEG
+@node if statement,,, Writing user defined functions
+@subsection @code{if} statement
+\E
 
 @noindent
-@code{if} $BJ8$K$O(B
+\JP @code{if} $BJ8$K$O(B
+\EG There are two forms of @code{if} statement.
 
 @example
+\BJP
 if ( $B<0(B )             if ( $B<0(B )
     $BJ8(B       $B5Z$S(B         $BJ8(B
 else
     $BJ8(B
+\E
+\BEG
+if ( expression )             if ( expression )
+     statement       and           statement
+else  
+     statement
+\E
 @end example
 
 @noindent
+\BJP
 $B$N(B 2 $B<oN`$,$"$k(B. $B$3$l$i$NF0:n$OL@$i$+$G$"$k$,(B, $BJ8$N0LCV$K(B @code{if} $BJ8(B
 $B$,Mh$?>l9g$KCm0U$rMW$9$k(B. $B<!$NNc$r9M$($F$_$h$&(B. 
+\E
+\BEG
+The interpretation of these forms are obvious.  However, be careful
+when another @code{if} statement comes at the place for `statement'.
+Let us examine the following example.
+\E
 
 @example
+\BJP
 if ( $B<0(B )
     if ( $B<0(B ) $BJ8(B
 else
     $BJ8(B
+\E
+\BEG
+if ( expression1 )
+    if ( expression2 ) statement1
+else  
+    statement2
+\E
 @end example
 
 @noindent
+\BJP
 $B$3$N>l9g(B, $B;z2<$2$+$i$O(B, @code{else} $B0J2<$O(B, $B:G=i$N(B @code{if} $B$KBP1~$9$k(B
 $B$h$&$K8+$($k$,(B, $B%Q!<%6$O(B, $B<+F0E*$K(B 2 $BHVL\$N(B @code{if} $B$KBP1~$9$k$HH=CG$9$k(B. 
 $B$9$J$o$A(B, 2 $B<oN`$N(B @code{if} $BJ8$r5v$7$?$?$a$K(B, $BJ8K!$K[#Kf@-$,8=$l(B, $B$=$l$r(B
 $B2r>C$9$k$?$a$K(B, @code{else} $B0J2<$O(B, $B:G$b6a$$(B @code{if} $B$KBP1~$9$k$H(B
 $B$$$&5,B'$,E,MQ$5$l$k$N$G$"$k(B. $B=>$C$F(B, $B$3$NNc$O(B, 
+\E
+\BEG
+One might guess @code{statement2} after @code{else} corresponds with the
+first @code{if ( expression1 )} by its appearance of indentation.
+But, as a matter of fact, the @code{Asir} parser decides that it
+correspond with the second @code{if ( expression2 )}.
+Ambiguity due to such two kinds of forms of @code{if} statement is
+thus solved by introducing a rule that a statement preceded by an
+@code{else} matches to the nearest preceding @code{if}.
+      
+Therefore, rearrangement of the above example for improving readability
+according to the actual interpretation gives the following.
+\E
 
 @example
+\BJP
 if ( $B<0(B ) @{
     if ( $B<0(B ) $BJ8(B else $BJ8(B
 @}
+\E
+\BEG
+if ( expression1 ) @{
+    if ( expression2 ) statement1 else statement2
+@}    
+\E
 @end example
 
 @noindent
-$B$H$$$&0UL#$H$J$k(B. $B;z2<$2$KBP1~$5$;$k$?$a$K$O(B, 
+\JP $B$H$$$&0UL#$H$J$k(B. $B;z2<$2$KBP1~$5$;$k$?$a$K$O(B, 
+\BEG
+On the other hand, in order to reflect the indentation, it must be
+written as the following.
+\E
 
 @example
+\BJP
 if ( $B<0(B ) @{
     if ( $B<0(B ) $BJ8(B
 @} else
     $BJ8(B
+\E
+\BEG
+if ( expression1 ) @{
+    if ( expression2 ) statement1
+@} else
+    statement2
+\E
 @end example
 
 @noindent
-$B$H$7$J$1$l$P$J$i$J$$(B. 
+\JP $B$H$7$J$1$l$P$J$i$J$$(B. 
 
+\BJP
 @node $B%k!<%W(B break return continue,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B%k!<%W(B, @code{break}, @code{return}, @code{continue}
+\E
+\BEG
+@node loop break return continue,,, Writing user defined functions
+@subsection @code{loop}, @code{break}, @code{return}, @code{continue}
+\E
 
 @noindent
+\BJP
 $B%k!<%W$r9=@.$9$kJ8$O(B, @code{while} $BJ8(B, @code{for} $BJ8(B, @code{do} $BJ8(B
 $B$N(B 3 $B<oN`$,$"$k(B. 
+\E
+\BEG
+There are three kinds of statements for loops (repetitions):
+the @code{while} statement, the @code{for} statement, and  the
+@code{do} statement.
+\E
 
 @itemize @bullet
 @item
-@code{while} $BJ8(B
+\JP @code{while} $BJ8(B
+\EG @code{while} statement
 
-$B7A<0$O(B, 
+\JP $B7A<0$O(B, 
+\EG It has the following form.
 
 @example
-while ( $B<0(B ) $BJ8(B
+\JP while ( $B<0(B ) $BJ8(B
+\EG while ( expression ) statement
 @end example
 
 @noindent
+\BJP
 $B$G(B, $B$3$l$O(B, $B<0(B $B$rI>2A$7$F(B, $B$=$NCM$,(B 0 $B$G$J$$8B$j(B $BJ8(B $B$r<B9T$9$k$H$$$&(B
 $B0UL#$H$J$k(B. $B$?$H$($P(B $B<0(B $B$,(B 1 $B$J$i$P(B, $BC1=c$JL58B%k!<%W$H$J$k(B. 
+\E
+\BEG
+This statement specifies that @code{statement} is repeatedly evaluated
+as far as the @code{expression} evaluates to a non-zero value.
+If the expression 1 is given to the @code{expression}, it forms an
+infinite loop.
+\E
 
 @item
-@code{for} $BJ8(B
+\JP @code{for} $BJ8(B
+\EG @code{for} statement
 
-$B7A<0$O(B, 
+\JP $B7A<0$O(B, 
+\EG It has the following form.
 
 @example
-for ( $B<0JB$S(B-1; $B<0(B; $B<0JB$S(B-2 ) $BJ8(B
+\JP for ( $B<0JB$S(B-1; $B<0(B; $B<0JB$S(B-2 ) $BJ8(B
+\EG for ( expression list-1; expression; expression list-2 ) statement
 @end example
 
-$B$G(B, $B$3$l$O(B
+\JP $B$G(B, $B$3$l$O(B
+\EG This is equivalent to the program
 
 @example
+\BJP
 $B<0JB$S(B-1 ($B$rC1J8JB$S$K$7$?$b$N(B)
 while ( $B<0(B ) @{
     $BJ8(B
     $B<0JB$S(B-2 ($B$rC1J8JB$S$K$7$?$b$N(B)
 @}
+\E
+\BEG
+expression list-1 (transformed into a sequence of simple statement)
+while ( expression ) @{
+    statement
+    expression list-2 (transformed into a sequence of simple statement)
+@}    
+\E
 @end example
 
-$B$HEy2A$G$"$k(B. 
+\JP $B$HEy2A$G$"$k(B. 
    
 @item
-@code{do} $BJ8(B
+\JP @code{do} $BJ8(B
+\EG @code{do} statement
 
 @example
+\BJP
 do @{
     $BJ8(B
 @} while ( $B<0(B )
+\E
+\BEG
+do @{ 
+    statement
+@} while ( expression )
+\E
 @end example
 
+\BJP
 $B$O(B, $B@h$K(B $BJ8$r<B9T$7$F$+$i>r7o<0$K$h$kH=Dj$r9T$&=j$,(B @code{while} $BJ8(B
 $B$H0[$J$C$F$$$k(B. 
+\E
+\BEG
+This statement differs from @code{while} statement by the location of
+the termination condition: This statement first execute the
+@code{statement} and then check the condition, whereas @code{while}
+statement does it in the reverse order.
+\E
 @end itemize
 
 @noindent
+\BJP
 $B%k!<%W$rH4$1=P$9<jCJ$H$7$F(B, 
 @code{break} $BJ85Z$S(B @code{return} $BJ8$,$"$k(B. $B$^$?(B, $B%k!<%W$N@)8f$r(B
 $B$"$k0LCV$K0\$9<jCJ$H$7$F(B @code{continue} $BJ8$,$"$k(B. 
-
+\E
+\BEG
+As means for exiting from loops, there are @code{break} statement and
+@code{return} statement.  The @code{continue} statement allows to move
+the control to a certain point of the loop.
+\E
 @itemize @bullet
 
 @item
 @code{break}
 
-@code{break} $BJ8$O(B, $B$=$l$r0O$`%k!<%W$r0l$D$@$1H4$1$k(B. 
-
+\JP @code{break} $BJ8$O(B, $B$=$l$r0O$`%k!<%W$r0l$D$@$1H4$1$k(B. 
+\EG The @code{break} statement is used to exit the inner most loop.
 @item
 @code{return}
 
+\BJP
 @code{return} $BJ8$O(B, $B0lHL$KH!?t$+$iH4$1$k$?$a$NJ8$G$"$j(B, 
 $B%k!<%W$NCf$+$i$G$bM-8z$G$"$k(B. 
+\E
+\BEG
+The @code{return} statement is usually used to exit from a function call
+and it is also effective in a loop.
+\E
 
 @item
 @code{continue}
 
+\BJP
 @code{continue} $BJ8$O(B, $B%k!<%W$NK\BN$NJ8$NKvC<$K@)8f$r0\$9(B. 
 $BNc$($P(B @code{for} $BJ8$G$O(B, $B:G8e$N<0JB$S$N<B9T$r9T$$(B, @code{while}
 $BJ8$G$O>r7o<0$NH=Dj$K0\$k(B. 
+\E
+\BEG
+The @code{continue} statement is used to move the control to the end
+point of the loop body.
+For example, the last expression list will be evaluated in a @code{for}
+statement, and the termination condition will be evaluated in a
+@code{while} statement.
+\E
 @end itemize
 
+\BJP
 @node $B$5$^$6$^$J<0(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B$5$^$6$^$J<0(B
+\E
+\BEG
+@node various expressions,,, Writing user defined functions
+@subsection various expressions
+\E
 
 @noindent
-$B<g$J<0$N9=@.MWAG$H$7$F$O(B, $B<!$N$h$&$J$b$N$,$"$k(B. 
+\JP $B<g$J<0$N9=@.MWAG$H$7$F$O(B, $B<!$N$h$&$J$b$N$,$"$k(B. 
+\EG Major elements to construct expressions are the following:
 
 @itemize @bullet
 @item
-$B2C8:>h=|(B, $BQQ(B
+\JP $B2C8:>h=|(B, $BQQ(B
+\EG addition, subtraction, multiplication, division, exponentiation
 
+\BJP
 $BQQ$O(B, @samp{^} $B$K$h$jI=$9(B. $B=|;;(B @samp{/} $B$O(B, $BBN$H$7$F$N1i;;$KMQ$$$k(B. 
 $BNc$($P(B, @code{2/3} $B$OM-M}?t$N(B @code{2/3} $B$rI=$9(B. 
 $B@0?t=|;;(B, $BB?9`<0=|;;(B ($B>jM>$r4^$`1i;;(B) $B$K$OJLESAH$_9~$_H!?t$,MQ0U$5$l$F$$$k(B. 
+\E
+\BEG
+The exponentiation is denoted by @samp{^}. (This differs from C language.)
+Division denoted by @samp{/} is used to operate in a field, for example,
+@code{2/3} results in a rational number @code{2/3}.
+For integer division and polynomial division, both including remainder
+operation, built-in functions are provided.
+\E
 
 @example
 x+1  A^2*B*afo X/3 
 @end example
 
 @item
-$B%$%s%G%C%/%9$D$-$NJQ?t(B
+\JP $B%$%s%G%C%/%9$D$-$NJQ?t(B
+\EG programming variables with indices
 
+\BJP
 $B%Y%/%H%k(B, $B9TNs(B, $B%j%9%H$NMWAG$O%$%s%G%C%/%9$rMQ$$$k$3$H$K$h$j<h$j=P$;$k(B. 
 $B%$%s%G%C%/%9$O(B 0 $B$+$i;O$^$k$3$H$KCm0U$9$k(B. $B<h$j=P$7$?MWAG$,%Y%/%H%k(B, 
 $B9TNs(B, $B%j%9%H$J$i(B, $B$5$i$K%$%s%G%C%/%9$r$D$1$k$3$H$bM-8z$G$"$k(B. 
+\E
+\BEG
+An element of a vector, a matrix or a list can be referred to by
+indexing.
+Note that the indices begin with number 0.  When the referred element
+is again a vector, a matrix or a list, repeated indexing is also
+effective.
+\E
 
 @example
 V[0] M[1][2]
 @end example
 
 @item
-$BHf3S1i;;(B
+\JP $BHf3S1i;;(B
+\EG comparison operation
 
+\BJP
 $BEy$7$$(B (@samp{==}), $BEy$7$/$J$$(B (@samp{!=}), $BBg>.(B (@samp{>}, @samp{<}, 
 @samp{>=}, @samp{<=}) $B$N(B 2 $B9`1i;;$,$"$k(B. $B??$J$i$PM-M}?t$N(B 1, $B56$J$i$P(B
 0 $B$rCM$K;}$D(B. 
+\E
+\BEG
+There are comparison operations
+@samp{==} for equivalence, @samp{!=} for non-equivalence,
+@samp{>}, @samp{<},@samp{>=}, and @samp{<=} for larger or smaller.
+The results of these operations are either value 1 for the truth,
+or 0 for the false.
+\E
 
 @item
-$BO@M}<0(B
+\JP $BO@M}<0(B
+\EG logical expression
 
+\BJP
 $BO@M}@Q(B (@samp{&&}), $BO@M}OB(B (@samp{||}) $B$N(B 2 $B9`1i;;$H(B, $BH]Dj(B (@samp{!})
 $B$,MQ0U$5$l$F$$$k(B. $BCM$O$d$O$j(B 1, 0 $B$G$"$k(B. 
+\E
+\BEG
+There are two binary logical operations
+@samp{&&} for logical @samp{conjunction}(and),
+@samp{||} for logical @samp{disjunction}(or),
+and one unary logical operation @samp{!} for logical @samp{negation}(not).
+The results of these operations are either value 1 for the truth,
+and 0 for the false.
+\E
 
 @item
-$BBeF~(B
+\JP $BBeF~(B
+\EG assignment
 
+\BJP
 $BDL>o$NBeF~$O(B @samp{=} $B$G9T$&(B. $B$3$N$[$+(B, $B;;=Q1i;;;R$HAH$_9g$o$;$F(B
 $BFC<l$JBeF~$r9T$&$3$H$b$G$-$k(B. 
+\E
+\BEG
+Value assignment of a program variable is usually done by @samp{=}.
+There are special assignments combined with arithmetic operations.
+\E
 (@samp{+=}, @samp{-=}, @samp{*=}, @samp{/=}, @samp{^=})
 
 @example
-A = 2  A *= 3 ($B$3$l$O(B A = A*3 $B$HF1$8(B; $B$=$NB>$N1i;;;R$bF1MM(B)
+\JP A = 2  A *= 3 ($B$3$l$O(B A = A*3 $B$HF1$8(B; $B$=$NB>$N1i;;;R$bF1MM(B)
+\EG A = 2  A *= 3 (the same as A = A*3; The other combination are alike.)
 @end example
 @item
-$BH!?t8F$S=P$7(B
+\JP $BH!?t8F$S=P$7(B
+\EG function call
 
-$BH!?t8F$S=P$7$b<0$N0l<o$G$"$k(B. 
-
+\JP $BH!?t8F$S=P$7$b<0$N0l<o$G$"$k(B. 
+\EG A function call is also an expression.
 @item
 @samp{++}, @samp{--}
 
-$B$3$l$i$O(B, $BJQ?t$NA08e$K$D$$$F(B, $B$=$l$>$l<!$N$h$&$JA`:n(B, $BCM$rI=$9(B. 
-
+\JP $B$3$l$i$O(B, $BJQ?t$NA08e$K$D$$$F(B, $B$=$l$>$l<!$N$h$&$JA`:n(B, $BCM$rI=$9(B. 
+\BEG
+These operators are attached to or before a program variable,
+and denote special operations and values.
+\E
 @example
+\BJP
 A++  $BCM$O85$N(B A $B$NCM(B, A = A+1
 A--  $BCM$O85$N(B A $B$NCM(B, A = A-1
 ++A  A = A+1, $BCM$OJQ2=8e$NCM(B
 --A  A = A-1, $BCM$OJQ2=8e$NCM(B
+\E
+\BEG
+A++  the expression value is the previous value of A, and A = A+1
+A--  the expression value is the previous value of A, and A = A-1
+++A  A = A+1, and the expression value is the value after increment of A
+--A  A = A-1, and the expression value is the value after decrement of A
+\E
 @end example
 
 @end itemize
 
+\BJP
 @node $B%W%j%W%m%;%C%5(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B%W%j%W%m%;%C%5(B
+\E
+\BEG
+@node preprocessor,,, Writing user defined functions
+@subsection preprocessor
+\E
 
 @noindent
+\BJP
 @b{Asir} $B$N%f!<%68@8l$O(B C $B8@8l$rLO$7$?$b$N$G$"$k(B. C $B$NFCD'$H$7$F(B, 
 $B%W%j%W%m%;%C%5(B @code{cpp} $B$K$h$k%^%/%mE83+(B, $B%U%!%$%k$N%$%s%/%k!<%I(B
 $B$,$"$k$,(B, @b{Asir} $B$K$*$$$F$b%f!<%68@8l%U%!%$%k$NFI$_9~$_$N:](B
 @code{cpp} $B$rDL$7$F$+$iFI$_9~$`$3$H$H$7$?(B. $B$3$l$K$h$j%f!<%68@8l(B
 $B%U%!%$%kCf$G(B @code{#include}, @code{#define}, @code{#if} $B$J$I$,;H$($k(B. 
+\E
+\BEG
+he @b{Asir} user language imitates C language.  A typical features of
+C language include macro expansion and file inclusion by the
+preprocessor @code{cpp}.  Also, @b{Asir} read in user program files
+through @code{cpp}.  This enables @b{Asir} user to use
+@code{#include}, @code{#define}, @code{#if} etc. in his programs.
+\E
 
 @itemize @bullet
 @item
 @code{#include}
 
+\BJP
 @code{cpp} $B$KFC$K0z?t$rEO$5$J$$$?$a(B, $B%$%s%/%k!<%I%U%!%$%k$O(B, 
 @code{#include} $B$,=q$+$l$F$$$k%U%!%$%k$HF1$8%G%#%l%/%H%j$G%5!<%A$5$l$k(B. 
+\E
+\BEG
+Include files are searched within the same directory as the file
+containing @code{#include} so that no arguments are passed to @code{cpp}.
+\E
 
 @item
 @code{#define}
 
-$B$3$l$O(B, C $B$K$*$1$k$N$HA4$/F1MM$KMQ$$$k$3$H$,$G$-$k(B. 
+\JP $B$3$l$O(B, C $B$K$*$1$k$N$HA4$/F1MM$KMQ$$$k$3$H$,$G$-$k(B. 
+\EG This can be used just as in C language.
 
 @item
 @code{#if}
 
+\BJP
 @code{/*}, @code{*/} $B$K$h$k%3%a%s%H$OF~$l;R$K$G$-$J$$$N$G(B, $B%W%m%0%i%`(B
 $B$NBg$-$JItJ,$r%3%a%s%H%"%&%H$9$k:]$K(B, @code{#if 0}, @code{#endif}
 $B$r;H$&$HJXMx$G$"$k(B. 
+\E
+\BEG
+This is conveniently used to comment out a large part of a user program
+that may contain comments by @code{/*} and @code{*/},
+because such comments cannot be nested.
+\E
 @end itemize
 
 @noindent
-$B<!$NNc$O(B, @samp{defs.h} $B$K$"$k%^%/%mDj5A$G$"$k(B. 
+\JP $B<!$NNc$O(B, @samp{defs.h} $B$K$"$k%^%/%mDj5A$G$"$k(B. 
+\EG the following are the macro definitions in @samp{defs.h}.
 
 @example
 #define ZERO 0
@@ -639,11 +1229,23 @@ A--  $BCM$O85$N(B A $B$NCM(B, A = A-1
 @end example
 
 
+\BJP
 @node $B%*%W%7%g%s;XDj(B,,, $B%f!<%6Dj5AH!?t$N=q$-J}(B
 @subsection $B%*%W%7%g%s;XDj(B
+\E
+\BEG
+@node option,,, Writing user defined functions
+@subsection option
+\E
 
+\BJP
 $B%f!<%6Dj5A4X?t$,(B @var{N} $BJQ?t$G@k8@$5$l$?>l9g(B, $B$=$N4X?t$O(B, @var{N}
 $BJQ?t$G$N8F$S=P$7$N$_$,5v$5$l$k(B. 
+\E
+\BEG
+If a user defined function is declared with @var{N} arguments,
+then the function is callable with @var{N} arguments only.
+\E
 
 @example
 [0] def factor(A) @{ return fctr(A); @}
@@ -652,8 +1254,15 @@ evalf : argument mismatch in factor()
 return to toplevel
 @end example
 
+\BJP
 $BITDj8D0z?t$N4X?t$r%f!<%68@8l$G5-=R$7$?$$>l9g(B, $B%j%9%H(B, $BG[Ns$rMQ$$$k$3$H$G(B
 $B2DG=$H$J$k$,(B, $B<!$N$h$&$J$h$jJ,$+$j$d$9$$J}K!$b2DG=$G$"$k(B. 
+\E
+\BEG
+A function with indefinite number of arguments can be realized by
+using a list or an array as its argument. Another method is available
+as follows:
+\E
 
 @example
 % cat factor
@@ -676,16 +1285,29 @@ def factor(F)
 [[1,1],[x+6,1],[x+2,1],[x+10,1],[x+7,1],[x+8,1]]
 @end example
 
+\BJP
 2 $BHVL\$N(B @code{factor()} $B$N8F$S=P$7$K$*$$$F(B, $B4X?tDj5A$N:]$K@k8@$5$l$?0z(B
-$B?t(B @var{x^5-1}$B$N8e$m$K(B @var{|mod=11} $B$,CV$+$l$F$$$k(B. $B$3$l$O(B, $B4X?t<B9T;~(B
-$B$K(B, @var{mod} $B$H$$$&(B keyword $B$KBP$7$F(B @var{11} $B$H$$$&CM$r3d$jEv$F$k$3$H(B
+$B?t(B @code{x^5-1}$B$N8e$m$K(B @code{|mod=11} $B$,CV$+$l$F$$$k(B. $B$3$l$O(B, $B4X?t<B9T;~(B
+$B$K(B, @code{mod} $B$H$$$&(B keyword $B$KBP$7$F(B @code{11} $B$H$$$&CM$r3d$jEv$F$k$3$H(B
 $B$r;XDj$7$F$$$k(B. $B$3$l$r%*%W%7%g%s;XDj$H8F$V$3$H$K$9$k(B. $B$3$NCM$O(B 
 @code{getopt(mod)} $B$G<h$j=P$9$3$H$,$G$-$k(B. 1 $BHVL\$N8F$S=P$7$N$h$&$K(B 
-@var{mod} $B$KBP$9$k%*%W%7%g%s;XDj$,$J$$>l9g$K$O(B, @code{getopt(mod)} $B$O7?(B
+@code{mod} $B$KBP$9$k%*%W%7%g%s;XDj$,$J$$>l9g$K$O(B, @code{getopt(mod)} $B$O7?(B
 $B<1JL;R(B -1 $B$N%*%V%8%'%/%H$rJV$9(B. $B$3$l$K$h$j(B, $B;XDj$,$J$$>l9g$NF0:n$r(B if $BJ8(B
 $B$K$h$j5-=R$G$-$k(B. @samp{|} $B$N8e$m$K$O(B, $BG$0U8D$N%*%W%7%g%s$r(B, @samp{,}
 $B$G6h@Z$C$F;XDj$9$k$3$H$,$G$-$k(B. 
-
+\E
+\BEG 
+In the second call of @code{factor()}, @code{|mod=11} is placed
+after the argument @code{x^5-1}, which appears in the declaration of
+@code{factor()}. This means that the value @code{11} is assigned to
+the keyword @code{mod} when the function is executed. The value 
+can be retrieved by @code{getopt(mod)}. We call such machinery
+@var{option}. If the option for @var{mod} is not specified,
+@code{getopt(mod)} returns an object whose type is -1. By this
+feature, one can describe the behaviour of the function when
+the option is not specified by @var{if} statements.
+After @samp{|} one can append any number of options seperated by @samp{,}.
+\E
 @example
 [100] xxx(1,2,x^2-1,[1,2,3]|proc=1,index=5);
 @end example