xintsession (7may21)

git-svn-id: svn://tug.org/texlive/trunk@59120 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 64 insertions, 80 deletions

diff --git a/Master/texmf-dist/doc/plain/xintsession/README.md b/Master/texmf-dist/doc/plain/xintsession/README.md
index c5bdd6b7b9f..5df362a399b 100644
--- a/Master/texmf-dist/doc/plain/xintsession/README.md
+++ b/Master/texmf-dist/doc/plain/xintsession/README.md
@@ -1,6 +1,6 @@
 # xintsession README #
 
-Release: 0.2 (2021-05-05)
+Release: 0.2a (2021-05-06)
 
 ## Usage ##
 
diff --git a/Master/texmf-dist/tex/plain/xintsession/xintsession.tex b/Master/texmf-dist/tex/plain/xintsession/xintsession.tex
index aa0e8540d21..4bc478e85cb 100644
--- a/Master/texmf-dist/tex/plain/xintsession/xintsession.tex
+++ b/Master/texmf-dist/tex/plain/xintsession/xintsession.tex
@@ -1,4 +1,4 @@
-% Release 0.2 (2021-05-05) of xintsession.tex
+% Release 0.2a (2021-05-06) of xintsession.tex
 % author: Jean-Francois Burnol
 % License: LPPL 1.3c (author-maintained)
 % Usage: execute etex or pdftex
@@ -47,7 +47,7 @@
   ___(_)________  /__________________ ________  /___(_)__   ______
   __  /__  __ \  __/  _ \_  ___/  __ `/  ___/  __/_  /__ | / /  _ \
   _  / _  / / / /_ /  __/  /   / /_/ // /__ / /_ _  / __ |/ //  __/
-  /_/  /_/ /_/\__/ \___//_/    \__,_/ \___/ \__/ /_/  _____/ \___/
+  /_/  /_/ /_/\__/ \___//_/    \__,_/ \___/ \__/ /_/  _____/ \___/%
 }%
 ?immediate?write128{%
 
@@ -242,138 +242,122 @@
 \catcode13\active\catcode32\active%
 \gdef\xintstart{\edef {\string }\xs_setcats\def
 {""J}\message{\xs_logo
-  Welcome to xintexpr interactive mode!
 
+  Welcome to xintexpr interactive mode!
   - input is `;'-terminated and can extend over multiple lines,
   - definitions must be done using the `:=' syntax, not `='.
+  - any line starting with a control sequence is executed in the
+    background, the interrupted numerical input resumes at prompt.
 
-  Any line starting with a control sequence is executed in the
-  background, the interrupted numerical input resumes at prompt.
-  Magic words: `&pause' (or `;'), `&help', `&bye'.
-  Mode toggles: `&exact', `&fp', `&int', `&pol'.  Say for example
-  `&fp=24' at the prompt to work with Digits=24 (Digits range: 1 to 62)
+  Magic words: `&pause' (or `;'), `&help', `&bye',
+               `&exact', `&fp', `&int', `&pol'.
+  Say e.g. `&fp=24' to activate floating point mode  with Digits=24.
   Starting in}\xs_magic@&exa\let
 =\xs_fetch}\gdef\xintresume{\edef {\string }\xs_storecats\xs_setcats%
 \message{Welcome back to xintexpr interactive mode!}\let
 =\xs_fetch}\catcode`?0\catcode`\\12?gdef?xs_help?xs_fetch_a{?def
 {""J}?edef {?string }?message{%
-  - Terminate inputs using the `;' character.
-
-  - Input can extend over multiple lines (<RET> terminated).
+  - Terminate inputs using the `;' character. Input can extend over
+    multiple lines (<RET> terminated).
 
   - An empty input (`;' terminated) or the magic word `&pause' puts
     the session on hold and switches to normal TeX interaction. Use
     \xintresume to resume the session.
 
+  - Lines starting with any control sequence are handed over to
+    TeX, and numerical input resumes on next line.
+
   - The numerical engine can work in various modes:
-    * exact mode means using \xintexpr context,
-    * fp mode uses \xintfloatexpr,
-    * int mode uses integer-only \xintiiexpr,
-    * pol mode makes function definitions using \poldef.
+    exact (uses \xintexpr), fp (uses \xintfloatexpr), int (uses
+    (\xintiiexpr), and pol (makes definitions using \poldef).
     To activate a mode enter `&<mode name>' at the prompt
 
-  - Lines starting with any control sequence are handed over to
-    TeX, and numerical input resumes on next line.
+  - Issue `&mode' if you forgot in what mode you are currently in.
 
-  - Say `&fp=<number>' for example `&fp=32' at the prompt to change
-    the Digits setting. This can be done in the midst of the
-    input of a  multi-line computation!
+  - Say `&exact' resp. `&fp' to go back and forth between exact
+    and floating point mode
 
-(1/5) HIT <RET> KEY
+(1/5) HIT <RET> KEY%
 }?let
 =?xs_help_b}?gdef?xs_help_b{?def
 {""J}?message{%
-  - Say `&exact' resp. `&fp' to go back and forth between exact
-    and floating point mode
+  - Say `&fp=<number>' for example `&fp=32' at the prompt to activate
+    fp mode at a given Digits setting. This can be done in the midst
+    of the input of a  multi-line computation!
 
-  - Issue `&mode' if you forgot in what mode you are currently in.
+  - Math functions are supported up to Digits=62 (since xint 1.4e);
+    sqrt() and powers with integer exponents work in fp mode with Digits
+    arbitrary.
 
   - Definitions (variables or functions) are done using `:='.
 
-    IMPORTANT: currently, using a `=' by oversight will cause
-    breakage because xintsession thinks it is then a numerical
-    evaluation, not a definition, but there is no `=' operator in
-    xintexpr syntax.
-
-    Perhaps in future it will be allowed to make definitions using
-    `=' and xintsession will check if it is not misinterpreting a
-    `=' from `<=', `>=', `!=', `==' or `seq()' syntax but this
-    currently was considered to add too much overhead for the
-    benefit.
-    
-  - Parentheses present before the `:=' trigger a function
-    definition, else a variable definition is done.
+    *  Parentheses present before the `:=' trigger a function
+       definition, else a variable definition is done.
 
-  - Functions defined in one mode are not available for usage in
-    other modes without further steps; check xintexpr doc.
+    *  IMPORTANT: using a `=' by oversight will cause breakage as
+    xintsession thinks it is then handling a numerical evaluation,
+    not a definition, but there is no `=' operator in xintexpr syntax.
 
-(2/5) HIT <RET> KEY
+%    Perhaps in future it will be allowed to make definitions using `='
+%    and xintsession will check if it is not misinterpreting a `=' from
+%    `<=', `>=', `!=', `==' or `seq()' syntax but this currently was
+%    considered to add too much overhead for the benefit.
+%    
+(2/5) HIT <RET> KEY%
 }?let
 =?xs_help_c}?gdef?xs_help_c{?def
 {""J}?message{%
-  - Polynomial definitions (pol mode) are function definitions (see
-    polexpr documentation). To use a polynomial also as a numerical
-    function when back in fp mode, issue
-    \PolGenFloatVariant{<polname>} at the prompt.
+  - Functions defined in one mode are not available for usage in
+    other modes without further steps; check xintexpr doc.
 
-  - Variables defined in any mode can be used in any mode except:
-    * polynomials can be used as variables only in the pol and the
-      exact modes,
-    * integer-only mode requires... integer-only variables, also
-      internally. Use in int mode num() or \xintiexpr...\relax as
-      wrapper around exact or fp variables, even integer-valued ones.
+  - Polynomials in pol mode are defined using polname(x):=expression;
+    (or with another letter). They can serve as functions in the exact
+    mode. To use a polynomial also as an fp mode function, issue
+    \PolGenFloatVariant{<polname>} at the prompt.
 
   - Whenever a variable is defined, or a computation is performed,
-    the result is assigned a label @_<integer>. These automatic
-    variables can then be used in subsequent computations.
+    the result is assigned a label @_<integer>. These labels are
+    variables which can then be used in subsequent computations.
+
+  - The special variables @_, @__, and @___ hold the last, next
+    to last and next to next to last evaluation results.
 
   - In the case of a multi-variable assignment (see xintexpr doc)
     the automatic variable @_<integer> holds the whole thing, which
     may be a nutple or an ople, in addition to individual variables.
 
-  - The special variables @_, @__, and @___ hold the last, next
-    to last and next to next to last evaluation results.
-
-(3/5) HIT <RET> KEY
+(3/5) HIT <RET> KEY%
 }?let
 =?xs_help_d}?gdef?xs_help_d{?def
 {""J}?message{%
+  - Variables defined in any mode can be used in any mode except:
+    * polynomials can be used as variables only in the pol and the
+      exact modes,
+    * integer-only mode requires... integer-only variables, also
+      internally. Use num() or \xintiexpr...\relax as wrappers in int
+      mode around exact or fp variables (even integer-valued ones).
+
   Known issues:
 
   - The [P] optional argument of \xintfloateval can not be used
     because it is not recognized by \xintdeffloatvar, one can use
     the float() function with its second argument.
 
-  - An \xintexpr...\relax wrapper inside fp mode or an
-    \xintiexpr...\relax one inside int mode can not start a line,
-    as it would trigger control sequence execution.
-    Start with 0+ or use parentheses.
-
-  - The definitive default output format of the exact and fp modes
-    are not yet decided at upstream xintexpr:
-    - trailing zeros are not trimmed,
-    - exact and fp modes print out floating point numbers in
-      diverging ways,
-    - exact mode does not reduce to lowest terms, use reduce().
+  - An \xintexpr...\relax wrapper can not start a line, as it would
+    trigger control sequence execution. Use parentheses or 0+\...
 
-  - By default, the ** and ^ operators operate _only_ with integer
-    exponents in exact mode and with half-integers in fp mode.
-    Fractional powers are available via the pow(x,a) function.
+  - Exact mode does not reduce to lowest terms, use reduce().
 
-(4/5) HIT <RET> KEY
+(4/5) HIT <RET> KEY%
 }?let
 =?xs_help_e}?gdef?xs_help_e{?def
 {""J}?message{%
-  Known issues (cont.):
-
-  - Refer to xintexpr \poormanloghack documentation on how to let
-    fractional powers be available with ** or ^, and check polexpr
-    documentation for related information.
-
+  (cont.)
   - A session transcript file is created which can be executed by
     eTeX to redo all calculations; however @_, @__, and @___ will
     not be defined in this context so need to be manually replaced
-    by the suitable @_<integer>.
+    by the suitable @_<integer>. The format of the transcript
+    is to be considered unstable at this stage.
 
   Future:
 
@@ -387,7 +371,7 @@
   case, try escaping using `S'.  It does work sometimes.
 
 (5/5) You are back to the xintexpr interactive session! (mode: ?xs_mode)
-      Use `&bye' to terminate the session and the TeX run.
+      Use `&bye' to terminate the session and the TeX run.%
 }?let
 =?xs_fetch?xs_fetch_a}?endgroup
 \let\xs_magic@&hel\xs_help