summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt')
-rw-r--r--Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt106
1 files changed, 57 insertions, 49 deletions
diff --git a/Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt b/Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt
index 028e68626f6..0c6ab082af7 100644
--- a/Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt
+++ b/Master/texmf-dist/doc/generic/polexpr/polexpr-ref.rst.txt
@@ -33,14 +33,11 @@ exactly arbitrarily big integers or fractions.
i.e. per default one ``a, .., z, A, .., Z`` (more letters can be declared
under Unicode engines).
-- ``polname`` consists of *letters*, *digits*, and also the ``_`` and
- ``'`` characters are allowed. The polynomial name **must** start with
- a letter: do not use the underscore ``_`` as *first character* of a
- polynomial name (even if of catcode letter). No warning is emitted
- but dire consequences will ensue. The ``@`` is also allowed
- (independently of its catcode "letter" or "other", which does not
- matter). It is recommended to avoid using it as first character,
- except for temporary polynomial variables.
+- ``polname`` is a word (no space) built with *letters*, *digits*, and
+ the ``@``, ``_`` and ``'`` characters are allowed. The polynomial
+ name **must** start with a letter.
+
+ For guidelines regarding ``_`` and ``@`` see Technicalities_.
- The colon before the equality sign is optional and its (reasonable)
catcode does not matter.
@@ -1079,7 +1076,8 @@ Non-expandable macros
*expression* can make use of previously defined polynomials.
Polynomial names must start with a letter and are constituted of
- letters, digits, underscores and the right tick ``'``.
+ letters, digits, underscores, the ``@`` (see Technicalities_) and
+ the right tick ``'``.
The whole xintexpr_ syntax is authorized, as long as the final
result is of polynomial type::
@@ -1100,17 +1098,16 @@ Non-expandable macros
and also other polynomials (via their names, thanks to previous
item).
- Notice that any function defined via ``\xintdeffunc`` and using
- only algebraic operations (and ople indexing or slicing operations)
- should work fine in ``\xintexpr/\xinteval`` with such polynomial
- names as argument.
+ Any function defined via ``\xintdeffunc`` and only algebraic
+ operations, as well as ople indexing or slicing operations, should
+ work fine in ``\xintexpr/\xinteval`` with such polynomial names as
+ argument.
- In the case of a constant polynomial, the xintexpr_ variable (not the
- internal data structure on which the package macros operate)
+ In the case of a constant polynomial, the xintexpr_ *variable* (not
+ the internal data structure on which the package macros operate)
associated to it is indistinguishable from a scalar, it is actually
a scalar and has lost all traces from its origins as a polynomial
(so for example can be used as argument to the ``cos()`` function).
-
The *function* on the other hand remains a one-argument function,
which simply has a constant value.
@@ -1122,7 +1119,7 @@ Non-expandable macros
Worse, a
previously existing floating point function of the same name will
- be let undefined again, to avoid hard to debug mismatches between
+ be made undefined again, to avoid hard to debug mismatches between
exact and floating point polynomials. This also applies when the
polynomial is produced not via ``\poldef`` or ``\PolDef`` but
as result of usage of the other package macros.
@@ -1187,21 +1184,21 @@ Syntax: ``\PolGenFloatVariant{<polname>}``
.. _PolTypeset:
-``\PolTypeset{}``
-~~~~~~~~~~~~~~~~~
+``\PolTypeset[]{}``
+~~~~~~~~~~~~~~~~~~~
-Syntax: ``\PolTypeset{<pol. expr.>}``
+Syntax: ``\PolTypeset[<letter>]{<pol. expr.>}``
Typesets in descending powers, switching to math mode if in text
mode, after evaluating the polynomial expression::
\PolTypeset{mul(x-i,i=1..5)}% possible since polexpr 0.8
- The letter used in the input expression is by default ``x``,
+ The letter used in the input is by default assumed to be ``x``,
but can be modified by a redefinition of `\\PolToExprInVar`_.
- It uses also by default the letter ``x`` on output but this one can
- be changed via an optional argument::
+ The letter used in the output is also by default ``x``. This one
+ can be changed on-the-fly via the optional ``<letter>``::
\PolTypeset[z]{polname or polynomial expression}
@@ -1294,17 +1291,19 @@ Syntax: ``\PolTypesetCmdPrefix{<raw_coeff>}``
.. _PolTypeset*:
-``\PolTypeset*{}``
-~~~~~~~~~~~~~~~~~~
+``\PolTypeset*[]{}``
+~~~~~~~~~~~~~~~~~~~~
-Syntax: ``\PolTypeset*{<pol. expr.>}``
+Syntax: ``\PolTypeset*[<letter>]{<pol. expr.>}``
- Typesets in ascending powers. Use ``[<letter>]`` optional argument
- (after the ``*``) to use another letter than ``x``.
+ Typesets in ascending powers. The ``<letter>`` optional argument
+ (after the ``*``) declares the letter to use in the *output*.
+ As for `\\PolTypeset <PolTypeset>`_, it defaults to ``x``.
+
+ To modify the expected ``x`` in the *input*, see `\\PolToExprInVar`_.
Extended at ``0.8`` to accept general expressions and not only
- polynomial names. Redefine `\\PolToExprInVar`_ to use in the
- expression another letter than default ``x``.
+ polynomial names.
.. _PolLet:
@@ -1667,17 +1666,20 @@ Syntax: ``\PolToSturm{<polname>}{<sturmname>}``
.. note::
- The declaration of the ``S_k``\ 's will overwrite
- with no warning previously declared polynomials with identical
- names ``S_k``. This is original reason why the macro expects two
- names: ``<polname>`` and ``<sturmname>``.
+ The declaration of the ``S_k``\ 's will overwrite with no warning
+ previously declared polynomials with identical names ``S_k``,
+ i.e. ``<sturmname>_k``. This is why the macro was designed
+ to expect two names: ``<polname>`` and ``<sturmname>``.
It is allowed to use the polynomial name ``P`` as Sturm chain
- name ``S``: ``\PolToSturm{f}(f}``, but of course fusing the
- namespaces is slightly dangerous. And, also `\\PolSturmIsolateZeros
- <PolSturmIsolateZeros_>`_ creates variables sharing
- the ``<sturmname>`` prefix, which must be taken into account to
- avoid name clashes.
+ name ``S``: ``\PolToSturm{P}{P}``, but this is considered bad
+ practice for the reason mentioned in the previous paragraph.
+
+ Furthermore, `\\PolSturmIsolateZeros <PolSturmIsolateZeros_>`_
+ creates xintexpr_ variables whose names start with
+ ``<sturmname>L_``, ``<sturmname>R_``, and ``<sturmname>Z_``, also
+ ``<sturmname>M_`` for holding the multiplicities, and this may
+ overwrite pre-existing user-defined xintexpr_ variables.
.. warning::
@@ -2300,7 +2302,9 @@ Syntax: ``\PolToExpr{<pol. expr.>}``
^^^^^^^^^^^^^^^^^^^
Defaults to ``x``: the letter used as the polynomial indeterminate
- in the macro input.
+ in the macro input::
+
+ \def\PolToExprInVar{x}% (default)
Recall that declared polynomials are more efficiently used in
algebraic expressions without the ``(x)``, i.e. ``P*Q`` is better
@@ -3086,16 +3090,20 @@ Syntax: ``\PolDecToString{decimal number}``
Technicalities
--------------
+- Do not use the underscore ``_`` as the *first character* of a
+ polynomial name, even if of catcode letter. This may cause an
+ infinite loop.
+
+- The ``@`` is allowed in the names of polynomials, independently of
+ whether it is of catcode letter or other. In defining macros which
+ will use ``\poldef`` to create polynomials it seems reasonable to
+ adopt the convention that ``@`` as *first* character in polynomial
+ names is to be reserved to temporary auxiliary polynomials.
+
+ .. attention::
-- The ``@`` is allowed in the name of a polynomial (independently of
- whether it is of catcode letter or other.) This has always been the
- case, but was not documented by polexpr prior to ``0.8``, as the
- author has never found the time to provide some official guidelines on
- how to name temporary variables and the ``@`` is used already as such
- internally; time has still not yet been found to review the situation
- but it seems reasonable to recommend at any rate to restrict usage of
- ``@`` to scratch variables of defined macros and to avoid using it to
- name document variable.
+ Do not use ``@_`` at start of polynomial names. This is reserved for
+ internal usage by the package.
- Catcodes are set temporarily by `\\poldef <poldef;_>`_ macro to safe
values prior to grab the polynomial expression up to the terminator