===================================================================
RCS file: /home/cvs/OpenXM_contrib/pari-2.2/doc/Attic/usersch2.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -p -r1.1 -r1.2
--- OpenXM_contrib/pari-2.2/doc/Attic/usersch2.tex	2001/10/02 11:16:57	1.1
+++ OpenXM_contrib/pari-2.2/doc/Attic/usersch2.tex	2002/09/11 07:26:42	1.2
@@ -1,4 +1,4 @@
-% $Id: usersch2.tex,v 1.1 2001/10/02 11:16:57 noro Exp $
+% $Id: usersch2.tex,v 1.2 2002/09/11 07:26:42 noro Exp $
 % Copyright (c) 2000  The PARI Group
 %
 % This file is part of the PARI/GP documentation
@@ -14,7 +14,7 @@ useful as a stand-alone tool. The operations and funct
 PARI and GP will be described in the next chapter. In the present one, we
 describe the specific use of the GP programmable calculator.
 
-For starting the calculator, the general commandline syntax is:
+For starting the calculator, the general command line syntax is:
 
 \kbd{gp [-s stacksize] [-p primelimit]}
 
@@ -26,7 +26,7 @@ parameters of GP, or \var{defaults}. See \secref{se:de
 list and explanation of all defaults, there are many more than just those
 two. These defaults can be changed by adding parameters to the input line
 as above, or interactively during a GP session or in a preferences file (also
-known as \kbd{gprc}).
+known as \tet{gprc}).
 
 \unix Some new features were developed on UNIX platforms, and depend heavily
 on the operating system in use. It is \var{possible} that some of these
@@ -252,8 +252,8 @@ The hacker's way to check if this is the case would be
 the string \kbd{RL\_PROMPT\_START\_IGNORE}. If it's there, you are safe.
 
 A more sensible way is to make some experiments, and get a more recent
-\kbd{readline} if yours doesn't work the way you'd like it to. See the file
-\kbd{misc/gprc.dft} for some examples.
+\kbd{readline} if yours doesn't work the way you would like it to. See the
+file \kbd{misc/gprc.dft} for some examples.
 
 \subsecidx{compatible} (default \kbd{0}): The GP function names and syntax
 have changed tremendously between versions 1.xx and 2.00. To help you cope
@@ -290,6 +290,9 @@ change modifies the function list, i.e.~if you move be
 $\{0,1\}$ and $\{2,3\}$ (variables are unaffected). We of course strongly
 encourage you to try and get used to the setting \kbd{compatible}=0.
 
+Note that the default \tet{new_galois_format} is another compatibility setting,
+which is completely independent of \kbd{compatible}.
+
 \subsecidx{debug} (default \kbd{0}): debugging level. If it is non-zero,
 some extra messages may be printed (some of it in French), according to
 what is going on (see~\b{g}).
@@ -362,6 +365,13 @@ be \var{appended} at the end.
 \subsecidx{logfile} (default \kbd{"pari.log"}): name of the log file to be
 used when the \kbd{log} toggle is on. Tilde and time expansion are performed.
 
+\subsecidx{new_galois_format} (default \kbd{0}): if this is set, the
+\tet{polgalois} command will use a different, more consistent, naming scheme
+for Galois groups. This default is provided to ensure that scripts
+can control this behaviour and do not break unexpectedly. Note that the
+default value of $0$ (unset) will change to $1$ (set) in the next major
+version.
+
 \subsecidx{output} (default \kbd{1}): there are four possible values: 0
 (=~\var{raw}), 1 (=~\var{prettymatrix}), 2 (=~\var{prettyprint}), or 3
 (=~\var{external prettyprint}). This
@@ -394,7 +404,7 @@ and~\b{b} respectively (see below).
 in fact any program using the PARI library, needs a stack in which to do
 its computations. \kbd{parisize} is the stack size, in bytes. It is
 strongly recommended you increase this default (using the \kbd{-s}
-command-line switch, or a \kbd{gprc}) if you can afford it. Don't increase
+command-line switch, or a \tet{gprc}) if you can afford it. Don't increase
 it beyond the actual amount of RAM installed on your computer or GP will
 spend most of its time paging.
 
@@ -452,6 +462,11 @@ Emacs relies on the prompt being the default one. So, 
 \kbd{.emacs} file (see \kbd{emacs/pariemacs.txt} and \kbd{misc/gprc.dft} for
 examples).
 
+\subsecidx{prompt_cont} (default \kbd{""}): a string that will be printed
+to prompt for continuation lines (e.g. in between braces, or after a
+line-terminating backslash). Everything that applies to \kbd{prompt}
+applies to \kbd{prompt\_cont} as well.
+
 \subsecidx{psfile} (default \kbd{"pari.ps"}): name of the default file where
 GP is to dump its PostScript drawings (these will always be appended, so that
 no previous data are lost). Tilde and time expansion are performed.
@@ -840,15 +855,17 @@ polynomial $y$. This allows us to work easily in \idx{
 extensions of the $p$-adic field $\Q_p$, or \idx{finite field}s.
 
 \label{se:rempolmod}
-\misctitle{Important remark.} Since the variables\sidx{variable} occurring
-in a polmod are not free variables, it is essential in order to avoid
-inconsistencies that polmods use the same variable in internal operations
-(i.e.~between polmods) and variables of lower priority (which have been
-introduced later in the GP session) for external operations (typically
-between a polynomial and a polmod). For example, PARI will not recognize
-that \kbd{Mod(y, y\pow2 + 1)} is the same as \kbd{Mod(x, x\pow2 + 1)}.
-Hopefully, this problem will pass away when type ``element of a number
-field'' is eventually introduced.
+\misctitle{Important remark.}\sidx{variable (priority)} Since the
+variables\sidx{variable} occurring in a polmod are not free variables, it is
+essential in order to avoid inconsistencies that polmods use the same
+variable in internal operations (i.e.~between polmods) and variables of lower
+priority (which have been introduced later in the GP session) for external
+operations (typically between a polynomial and a polmod). For example, PARI
+will not recognize that \kbd{Mod(y, y\pow2 + 1)} is the same as \kbd{Mod(x,
+x\pow2 + 1)}. Hopefully, this problem will pass away when type ``element of a
+number field'' is eventually introduced. See \secref{se:priority} for a
+definition of ``priority'' and a discussion of (PARI's idea of) multivariate
+polynomial arithmetic.
 
 On the other hand, \kbd{Mod(x, x\pow2 + 1) + Mod(x, x\pow2 + 1)}
 (which gives \kbd{Mod(2*x, x\pow2 + 1)}) and \kbd{x + Mod(y, y\pow2 + 1)}
@@ -876,7 +893,8 @@ functions, which you ought to know about (use \b{u} if
 memory lapses). The total number of different variable names is limited to
 $16384$ and $65536$ on 32-bit and 64-bit machines respectively, which
 should be enough. If you ever need hundreds of variables, you should
-probably be using vectors instead.
+probably be using vectors instead. See \secref{se:priority} for a discussion 
+of multivariate polynomial rings.
 
 \subsec{Power series}\sidx{power series}\label{se:series}
 (type \tet{t_SER}): type a rational function or
@@ -969,7 +987,8 @@ is equivalent to
 $$ x~\var{op}_1~((y~\var{op}_2~z)~\var{op}_2~ (x~\var{op}_3~y)).$$
 
 GP knows quite a lot of different operators, some of them unary (having
-only one argument), some binary. Unary operators are defined for either
+only one argument), some binary, plus special selection operators. Unary
+ operators are defined for either
 prefix (preceding their single argument: \var{op}~$x$) or postfix (following
 the argument: $x$~\var{op}) position, never both
 (some are syntactically correct in both positions, but with different
@@ -987,36 +1006,46 @@ will probably be more legible).
 binary unless mentioned otherwise):
 
 \def\point#1{\noindent $\bullet$ #1\hfill\break\indent\strut}
-\point{Priority 9}
+\point{Priority 10}
 %
 \kbd{++} and \kbd{--} (unary, postfix): \kbd{$x$++} assigns the value $x+1$ to
 $x$, then returns the new value of $x$. This corresponds to the C
 statement \kbd{++$x$} (there is no prefix \kbd{++} operator in GP).
 \kbd{$x$--} does the same with $x-1$.
 
-\point{Priority 8}
+\point{Priority 9}
 %
 \kbd{\var{op}=}, where \var{op} is any simple binary operator
 (i.e.~a binary operator with no side effects, i.e.~one of those defined below)
 which is not a boolean operator (comparison or logical).
 \kbd{x~\var{op}=~$y$} assigns $(\kbd{x}~\var{op}~y)$ to~\kbd{x},
 and returns the new value of~\kbd{x}, \var{not} a reference to the
-\idx{variable}~\kbd{x}. (Thus an assignment cannot occur on the lefthand
+\idx{variable}~\kbd{x}. (Thus an assignment cannot occur on the left hand
 side of another assignment.)
 
-\point{Priority 7}
+\point{Priority 8}
 %
 \kbd{=} is the assignment operator. The result of \kbd{x~=~$y$} is the value
 of the expression~$y$, which is also assigned to the variable~\kbd{x}. This
 is \var{not} the equality test operator. Beware that a statement like
 \kbd{x~=~1} is always true (i.e.~non-zero), and sets \kbd{x} to~1.
+The right hand side of the assignment operator is evaluated before the left
+hand side. If the left hand side cannot be modified, raise an error.
 
+\point{Priority 7}
+\kbd{[ ]} is the selection operator. \kbd{$x$[$i$]} returns the $i$-th
+component of vector $x$; \kbd{$x[$i$,$j$]$}, \kbd{$x[,$j$]$} and
+\kbd{$x$[$i$,]} respectively return the entry of coordinates $(i,j)$, the
+$j$-th column, and the $i$-th row of matrix $x$. If the assignment operator
+(\kbd{=}) immediately follows a sequence of selections, it assigns its
+right hand side to the selected component. E.g \kbd{x[1][1] = 0} is valid;
+but beware that \kbd{(x[1])[1] = 0} is not (because the parentheses force
+the complete evaluation of \kbd{x[1]}, and the result is not modifiable).
+
 \point{Priority 6}
 %
-\kbd{!} (unary, prefix): logical \var{not}. \kbd{!$x$} return $1$ if $x$ is
-equal to $0$ (specifically, if \kbd{gcmp0($x$)==1}), and $0$ otherwise.
-
-\kbd{'} (unary, prefix): quote its argument without evaluating it.
+\kbd{'} (unary, prefix): quote its argument (a variable name) without
+evaluating it.
 \bprog
 ? a = x + 1; x = 1;
 ? subst(a,x,1)
@@ -1025,8 +1054,6 @@ equal to $0$ (specifically, if \kbd{gcmp0($x$)==1}), a
 ? subst(a,'x,1)
 %1 = 2
 @eprog
-
-\point{Priority 5}
 %
 \kbd{\pow}: powering.
 
@@ -1040,8 +1067,16 @@ current precision. It behaves as $(f(x))'$ otherwise.
 
 \kbd{!} (unary, postfix): factorial. $x\kbd{!}=x(x-1)\cdots 1$.
 
-\kbd{.}: \kbd{$x$.$b$} extracts member $b$ from structure $x$.
+\kbd{.}\var{member} (unary, postfix): \kbd{$x$.\var{member}} extracts
+\var{member} from structure $x$ (see~\secref{se:member}).
 
+\point{Priority 5}
+%
+\kbd{!} (unary, prefix): logical \var{not}. \kbd{!$x$} return $1$ if $x$ is
+equal to $0$ (specifically, if \kbd{gcmp0($x$)==1}), and $0$ otherwise.
+
+\kbd{\#} (unary, prefix): cardinality; \kbd{\#$x$} returns \kbd{length($x$)}.
+
 \point{Priority 4}
 %
 \kbd{+}, \kbd{-} (unary, prefix): \kbd{-} toggles the sign of its argument,
@@ -1053,16 +1088,16 @@ current precision. It behaves as $(f(x))'$ otherwise.
 
 \kbd{/}: exact division (\kbd{3/2}=$3/2$, not $1.5$).
 
-\kbd{\bs}, \kbd{\%}: euclidean quotient and remainder, i.e.~if $x =
+\kbd{\bs}, \kbd{\%}: Euclidean quotient and remainder, i.e.~if $x =
 qy + r$, with $0\le r < y$ (if $x$ and $y$ are polynomials, assume instead
 that $\deg r< \deg y$ and that the leading terms of $r$ and $x$ have the
 same sign), then $\kbd{x \b{ } y} = q$, $\kbd{x\%y} = r$.
 
-\kbd{\bs/}: rounded euclidean quotient for integers (rounded towards
+\kbd{\bs/}: rounded Euclidean quotient for integers (rounded towards
 $+\infty$ when the exact quotient would be a half-integer).
 
 \kbd{<<}, \kbd{>>}: left and right binary shift: \kbd{x<<n}$~=~x * 2^n$
-if $n>0$, and $x \b{/} 2^{-n}$ otherwise; and
+if $n>0$, and $x \b{/} 2^{-n}$ otherwise. Right shift is defined by
 \kbd{x>>n}$~=~$\kbd{x<<(-n)}.
 
 \point{Priority 2}
@@ -1090,7 +1125,7 @@ and aborted as soon as the final truth value is known.
 produce an error since the second argument need not (and will not) be processed
 when the first is already zero (false).
 
-\misctitle{Remark:} For the optimal efficiency, you should use the
+\misctitle{Remark:} For optimal efficiency, you should use the
 \kbd{++}, \kbd{--} and \var{op}\kbd{=} operators whenever possible:
 \bprog
 ? a = 200000;
@@ -1142,11 +1177,11 @@ version $1.900$ on, there\sidx{case distinction} \var{
 between lowercase and uppercase. Also, note that, outside of constant
 strings, blanks are completely ignored in the input to GP.
 
-The special variable\sidx{variable (special)} names known to GP are
-\tet{Euler} (Euler's constant $\gamma=0.577\dots$), \tet{I} (the
-square root of $-1$), \tet{Pi} (3.14\dots)~--- which could be thought of as
-functions with no arguments, and which may therefore be invoked without
-parentheses~---, and \tet{O} which obeys the following syntax:
+The special variable names known to GP are \tet{Euler} (Euler's constant
+$\gamma=0.577\dots$), \tet{I} (the square root of $-1$), \tet{Pi}
+(3.14\dots)~--- which could be thought of as functions with no arguments, and
+which may therefore be invoked without parentheses~---, and \tet{O} which
+obeys the following syntax:
 
 \kbd{O(\var{expr}\pow k)}
 
@@ -1248,7 +1283,7 @@ manipulation package, although it shares some of the f
 the main consequences of this fact is that all expressions are evaluated as
 soon as they are written, they never stay in a purely abstract form%
 \footnote{**}{An obvious but important exception are character strings which
-are evaluated\dots\ essentially to themselves (type \typ{STR}). Not exactly
+are evaluated essentially to themselves (type \typ{STR}). Not exactly
 so though, since we do some work to treat the quoted characters correctly
 (those preceded by a \b{)}.}.
 %
@@ -1277,19 +1312,7 @@ to restrict the use of a given variable by declaring i
 \tet{local}. This can be useful to enforce clean programming style, but is in
 no way mandatory.
 
-\misctitle{(Technical) Note:} Variables are numbered in the order that they
-appear since the beginning of the session, and the main variable of an
-expression is always the lowest numbered variable. Hence if you are working
-with expressions involving several variables and want to have them ordered in
-a specific manner {\it in the internal representation}, the simplest is just
-to write down the variables one after the other under GP before starting any
-real computations. If you already have started working and want to change the
-names of the variables in an object, use the function \tet{changevar}. If you
-only want to have them ordered when the result is printed, you can also use
-the function \tet{reorder}, but this won't change anything to the internal
-representation.
-
-\misctitle{(Very technical) Note:}
+\misctitle{(Technical) Note:}
 Each variable has a stack of values, implemented as a linked list. When a new
 scope is entered (during a function call which uses it as a parameter, or if
 the variable is used as a loop index, see \secref{se:user_defined} and
@@ -1297,12 +1320,104 @@ the variable is used as a loop index, see \secref{se:u
 stack. If the parameter is not supplied, a special $0$ value called
 \teb{gnil} is pushed on the stack (this value is not printed if it is
 returned as the result of a GP expression sequence). Upon exit, the stack
-decreases. You can \kbd{kill} a variable, decreasing the stack yourself. This
-should be used only at the top level of GP, to undo the effect of an
-assignment, not from a function. However, the stack has a bottom: the value
-of a variable is the monomial of degree 1 in this variable, as is natural for
-a mathematician.
+decreases. You can \kbd{kill} a variable, decreasing the stack yourself.
+However, the stack has a bottom: the value of a variable is the monomial of
+degree 1 in this variable, as is natural for a mathematician.
 
+\subsec{Variable priorities:}\sidx{variable (priority)}\label{se:priority}
+PARI has no intelligent ``sparse'' representation of polynomials. So a
+multivariate polynomial in PARI is just a polynomial (in one variable), whose
+coefficients are themselves polynomials, arbitrary but for the fact that they 
+do not involve the main variable. All computations are then just done
+formally on the coefficients as if the polynomial was univariate.
+
+This is not symmetrical. So if I enter \kbd{x + y} in a clean session,
+what happens ? This is understood as
+$$ x^1 + y*x^0 \in (\Z[y])[x] $$
+but how can GP decide that $x$ is ``more important'' than $y$ ? Why not
+$y^1 + x*y^0$, which is the same mathematical entity after all ?
+
+The answer is that variables are ordered implicitly by the GP interpreter:
+when a new identifier (e.g~$x$, or $y$ as above) is input, the corresponding
+variable is registered as having a strictly lower priority than any variable in
+use at this point\footnote{*}{This is not strictly true: if an
+identifier is interpreted as a user function, no variable is registered. Also,
+the variable $x$ is predefined and always has the highest possible priority.}
+%
+. To see the ordering used by GP at any given time, type $\tet{reorder}()$.
+
+Given such an ordering, multivariate polynomials are stored so that the
+variable with the highest priority is the main variable. And so on,
+recursively, until all variables are exhausted. A different storage pattern
+(which could only be obtained via library mode) would produce an illegal
+object, and eventually a disaster.
+
+In any case, if you are working with expressions involving several variables
+and want to have them ordered in a specific manner in the internal
+representation just described, the simplest is just to write down the
+variables one after the other under GP before starting any real computations.
+You could also define variables from your GPRC to have a consistant
+ordering of common variable names in all your GP sessions, e.g read in a file
+\kbd{variables.gp} containing
+\bprog
+x;y;z;t;a;b;c;d
+@eprog
+
+If you already have started working and want to change the names of the
+variables in an object, use the function \tet{changevar}. If you only want to
+have them ordered when the result is printed, you can also use the function
+\tet{reorder}, but this won't change anything to the internal representation,
+and is not recommended.
+
+\misctitle{Important note:} PARI allows Euclidean division of multivariate
+polynomials, but assumes that the computation takes place in the fraction
+field of the coefficient ring (if it is not an integral domain, the result
+will a priori not make sense). This can be very tricky; for instance
+assume $x$ has highest priority (which is always the case), then
+$y$:
+\bprog
+? x % y
+%1 = 0
+? y % x
+%2 = y             \\@com these two take place in $\Q(y)[x]$
+? x * Mod(1,y)
+%3 = Mod(1, y)*x   \\@com in $(\Q(y)/y\Q(y))[x] \sim \Q[x]$
+? Mod(x,y)
+%4 = 0
+@eprog
+\noindent In the last exemple, the division by $y$ takes place in
+$\Q(y)[x]$, 
+hence the \kbd{Mod} object is a coset in $(\Q(y)[x]) / (y\Q(y)[x])$, which
+is the null ring since $y$ is invertible! So be very wary of variable
+ordering when your computations involve implicit divisions and many
+variables. This also affects functions like \tet{numerator}/\tet{denominator}
+or \tet{content}:
+\bprog
+? denominator(x / y)
+%1 = 1
+? denominator(y / x)
+%2 = x
+? content(x / y)
+%3 = 1/y
+? content(y / x)
+%4 = 1
+? content(2 / x)
+%5 = 2
+@eprog
+\noindent Can you see why ? Hint: $x/y = (1/y) * x$ is in $\Q(y)[x]$ and
+denominator is taken with respect to $\Q(y)(x)$; $y/x = (y*x^0) / x$ is in
+$\Q(y)(x)$ so $y$ is invertible in the coefficient ring. On the other hand,
+$2/x$ involves a single variable and the coefficient ring is simply $\Z$.
+
+These problems arise because the variable ordering defines an {\it
+implicit} variable with respect to which division takes place. This is
+the price to pay to allow \kbd{\%} and \kbd{/} operators on polynomials
+instead of requiring a more cumbersome \kbd{divrem($x$, $y$, \var{var})}
+(which also exists). Unfortunately, in some functions like \tet{content} and
+\tet{denominator}, there is no way to set explicitly a main variable like in
+\tet{divrem} and remove the dependance on implicit orderings. This will
+hopefully be corrected in future versions.
+
 \subsec{Expressions and expression sequences}.
 
   An \idx{expression}\sidx{expression sequence} is formed by combining the
@@ -1549,6 +1664,7 @@ introduced in version 2.0.13. The old syntax
 local variables become undistinguishable.
 
 \subsec{Member functions}.\sidx{member functions}
+\label{se:member}
 
 Member functions use the `dot' notation to retrieve information from
 complicated structures (by default: types \tet{ell}, \tet{nf}, \tet{bnf},
@@ -1657,20 +1773,29 @@ while the second (before the \kbd{"b"}) is completely 
 actually suppresses it, as it would with any number of whitespace characters
 at this point (i.e.~outside of any string).
 
-$\bullet$ If you insert an expression without quotes when GP expects a
-string, it gets ``expanded'': it is evaluated as a standard GP expression,
-and the final result (as would have been printed if you had typed it by
-itself) is then converted to a string, as if you had typed it directly. For
-instance \kbd{"a" 1+1 "b"} is equivalent to \kbd{"a2b"}: three strings get
-created, the middle one being the expansion of \kbd{1+1}, and these are then
-concatenated according to the rule described above. Another tricky point
-here: assume you did not assign a value to \kbd{aaa} in a GP expression
-before. Then typing \kbd{aaa} by itself in a string context will actually
-produce the correct output (i.e.~the string whose content is aaa), but in a
-fortuitous way. This \kbd{aaa} gets expanded to the monomial of degree one in
-the variable \kbd{aaa}, which is of course printed as \kbd{aaa}, and thus
-will expand to the three letters you were expecting.
+$\bullet$ If you insert any expression when GP expects a string, it gets
+``expanded'': it is evaluated as a standard GP expression, and the final
+result (as would have been printed if you had typed it by itself) is then
+converted to a string, as if you had typed it directly. For instance \kbd{"a"
+1+1 "b"} is equivalent to \kbd{"a2b"}: three strings get created, the middle
+one being the expansion of \kbd{1+1}, and these are then concatenated
+according to the rule described above. Another tricky point here: assume you
+did not assign a value to \kbd{aaa} in a GP expression before. Then typing
+\kbd{aaa} by itself in a string context will actually produce the correct
+output (i.e.~the string whose content is aaa), but in a fortuitous way. This
+\kbd{aaa} gets expanded to the monomial of degree one in the variable
+\kbd{aaa}, which is of course printed as \kbd{aaa}, and thus will expand to
+the three letters you were expecting.
 
+\misctitle{Warning:} expression involving strings are not handled in a
+special way; even in string context, the largest possible expression is
+evaluated, hence \kbd{print("a"[1])} is incorrect since \kbd{"a"} is not an
+object whose first component can be extracted. On the other hand
+\kbd{print("a", [1])} is correct (two distinct argument, each converted to a
+string), and so is \kbd{print("a" 1)} (since \kbd{"a"1} is not a valid
+expression, only \kbd{"a"} gets expanded, then \kbd{1}, and the result is
+concatenated as explained above).
+
 $\bullet$ Since there are cases where expansion is not really desirable, we
 now distinguish between ``Keywords'' and ``Strings''. String is what has been
 described so far. Keywords are special relatives of Strings which are
@@ -1794,12 +1919,21 @@ To our knowledge, only the \kbd{python} and \kbd{perl}
 upgraded to version 2.0 of PARI, the \kbd{CLISP} one being still based on
 version 1.39.$xx$.
 
-\section{The preferences file}\sidx{startup}\sidx{gprc}\sidx{preferences file}
+\section{The preferences file}\sidx{startup}\sidx{preferences file}
 \label{se:gprc}
 
-\noindent
+This file, called \tet{gprc} in the sequel, is used to modify or extend GP
+default behaviour, in all GP sessions: e.g customize \kbd{default} values or
+load common user functions and aliases. GP opens the \kbd{gprc} file and
+processes the commands in there, \var{before} doing anything else,
+e.g.~creating the PARI stack. If the file does not exist or cannot be read,
+GP will proceed to the initialization phase at once, eventually emitting a
+prompt. If any explicit command line switches are given, they override the
+values read from the preferences file.
+
+\subsec{Where is it?}
 When GP is started, it looks for a customization file, or \kbd{gprc} in the
-following places (in this order, only the first one found will be read):
+following places (in this order, only the first one found will be loaded):
 
 \noindent$\bullet$ On the Macintosh (only), GP looks in the directory which
 contains the GP executable itself for a file called \kbd{gprc}. No other places
@@ -1837,69 +1971,103 @@ your home directory), or
 
 \noindent$\bullet$ Finally, if no gprc was found among the user files
 mentioned above we look for \kbd{/etc/gprc} (\kbd{\bs etc\bs gprc})
-for a system-wide gprc file (you'll need root privileges to set up such a
+for a system-wide gprc file (you will need root privileges to set up such a
 file yourself).
 
 Note that on Unix systems, the \kbd{gprc}'s default name starts with a '.' and
 thus is hidden to regular \kbd{ls} commands; you need to type \kbd{ls -a} to
-see whether it's already there without your knowing about it.
+list it.
 
-In any case, GP will open the corresponding file and process the commands in
-there, \var{before} doing anything else, e.g.~creating the PARI stack. If
-the file doesn't exist or cannot be read, GP will proceed to the
-initialization phase at once, eventually emitting a prompt. If any explicit
-commandline switches are given, they will override the values read from the
-\kbd{gprc} file.
+\subsec{Syntax}
 
-The syntax in this file (and valid in this file only, at this very precise
-moment!) is simple-minded, but should be sufficient for most purposes. It
-is read line by line, white space being optional as usual (unless surrounded
-by quotes). Two types of lines are first dealt with by a preprocessor:
+The syntax in the \kbd{gprc} file (and valid in this file only) is
+simple-minded, but should be sufficient for most purposes. The file is read
+line by line; as usual, white space is ignored unless surrounded by quotes
+and the standard multiline constructions using braces, \kbd{\bs}, or \kbd{=}
+are available (multiline comments between \kbd{/*~\dots~*/} are also
+recognized).
 
+\subsubsec{Preprocessor:}
+Two types of lines are first dealt with by a preprocessor:
+
 $\bullet$ comments are removed. This applies to all text surrounded by
-\kbd{/*~\dots~*/} as well as everything following \kbd{\bs\bs} on a given
+\kbd{/*~\dots~*/} as well as to everything following \kbd{\bs\bs} on a given
 line.
 
-$\bullet$ lines starting with \kbd{\#if} \var{keyword} are treated as
-comments if \var{keyword} is not defined, and read normally otherwise. The
-condition can be negated using either \kbd{\#if not} (or \kbd{\#if !}). Only
-two keywords are recognized:
+$\bullet$ lines starting with \kbd{\#if} \var{boolean} are treated as
+comments if \var{boolean} evaluates to \kbd{false}, and read normally
+otherwise. The condition can be negated using either \kbd{\#if not} (or
+\kbd{\#if !}). If the rest of the current line is empty, the test applies to
+the next line (same behaviour as \kbd{=} under GP). Only three tests can be
+performed:
 
-\kbd{EMACS}: defined if GP is running in an Emacs shell (see
+\kbd{EMACS}: \kbd{true} if GP is running in an Emacs or TeXmacs shell (see
 \secref{se:emacs}).
 
-\kbd{READL}: defined if GP is compiled with \kbd{readline} support (see
+\kbd{READL}: \kbd{true} if GP is compiled with \kbd{readline} support (see
 \secref{se:readline}).
 
-\noindent For instance you could set your prompt in the following portable
-way:
+\kbd{VERSION} \var{op} \var{number}: where \var{op} is in the set
+$\{ \kbd{>}, \kbd{<}, \kbd{<=}, \kbd{>=} \}$, and \var{number} is a PARI
+version number of the form \var{Major}.\var{Minor}.\var{patch}, where the
+last two components can be omitted (i.e.~$1$ is understood as versio $1.0.0$).
+This is \kbd{true} if GP's version number satisfies the required
+inequality.
+
+\subsubsec{Commands:}
+After the preprocessing the remaining lines are executed as
+sequence of expressions (as usual, separated by \kbd{;} if necessary). Only
+two kinds of expressions are recognized:
+
+$\bullet$ \var{default} \kbd{=} \var{value}, where \var{default} is one of
+the available defaults (see \secref{se:defaults}), which will be set to
+\var{value} on actual startup. Don't forget the quotes around strings
+(e.g.~for \kbd{prompt} or \kbd{help}).
+
+$\bullet$ \kbd{read "\var{some\_GP\_file}"} where \kbd{\var{some\_GP\_file}}
+is a regular GP script this time, which will be read just before GP prompts
+you for commands, but after initializing the defaults. In particular, file
+input is delayed until the \kbd{gprc} has been fully loaded. This is the
+right place to input files containing \kbd{alias} commands, or your favorite
+macros.
+
+\noindent For instance you could set your prompt in the following portable way:
 \bprog
 \\ self modifying prompt looking like @com\hbox{\rm(18:03) \key{gp}\kbd{ >}}
 prompt   = "(\%R) \e[1mgp\e[m > "
 
 \\ readline wants non-printing characters to be braced between ^A/^B pairs
-#if READL  prompt = "(%R) ^A\e[1m^Bgp^A\e[m^B > "
+#if READL prompt = "(%R) ^A\e[1m^Bgp^A\e[m^B > "
 
 \\ escape sequences not supported under emacs
-#if EMACS  prompt = "(%R) gp > "
+#if EMACS prompt = "(%R) gp > "
 @eprog
 
-\noindent After the preprocessing there remain two types of lines:
+\noindent Note that any of the last two lines could be broken in the
+following way
+\bprog
+#if EMACS
+  prompt = "(%R) gp > "
+@eprog
+\noindent since the preprocessor directive applies to the next line if the
+current one is empty.
 
-$\bullet$ lines of the form \var{default} \kbd{=} \var{value}, where
-\var{default} is one of the available defaults (see \secref{se:defaults}),
-which will be set to \var{value} on actual startup. Don't forget the
-quotes around strings (e.g.~for \kbd{prompt} or \kbd{help}).
-
-$\bullet$ lines of the form \kbd{read "\var{some\_GP\_file}"} where
-\kbd{\var{some\_GP\_file}} is a regular GP script this time, which will
-be read just before GP prompts you for commands, but after initializing the
-defaults. This is the right place to input files containing \kbd{alias}
-commands, or your favorite macros.
-
-A sample \kbd{gprc} file called \kbd{gprc.dft} is provided in the
-standard distribution (in directory \kbd{lib}). It's a good idea to have a
-look at it and customize it to your needs.
+A sample \kbd{gprc} file called \kbd{misc/gprc.dft} is provided in the
+standard distribution. It is a good idea to have a look at it and customize
+it to your needs. Since this file does not use multiline constructs, here is
+one (note the terminating \kbd{;} to separate the expressions):
+\bprog
+#if VERSION > 2.2.3
+{
+  read "my_scripts";     \\ syntax errors in older versions
+  new_galois_format = 1; \\ default introduced in 2.2.4
+}
+#if ! EMACS
+{
+  colors = "9, 5, no, no, 4, 1, 2";
+  help   = "gphelp -detex -ch 4 -cb 0 -cu 2";
+}
+@eprog
 
 \section{Using GP under GNU Emacs}
 \label{se:emacs}