From 33fe673e1a4a678f76e23a91da0f449998af9c47 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Fri, 20 May 2022 03:01:51 +0000 Subject: CTAN sync 202205200301 --- macros/generic/polexpr/polexpr-ref.rst.txt | 106 ++++++++++++++++------------- 1 file changed, 57 insertions(+), 49 deletions(-) (limited to 'macros/generic/polexpr/polexpr-ref.rst.txt') diff --git a/macros/generic/polexpr/polexpr-ref.rst.txt b/macros/generic/polexpr/polexpr-ref.rst.txt index 028e68626f..0c6ab082af 100644 --- a/macros/generic/polexpr/polexpr-ref.rst.txt +++ b/macros/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{}`` .. _PolTypeset: -``\PolTypeset{}`` -~~~~~~~~~~~~~~~~~ +``\PolTypeset[]{}`` +~~~~~~~~~~~~~~~~~~~ -Syntax: ``\PolTypeset{}`` +Syntax: ``\PolTypeset[]{}`` 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 ````:: \PolTypeset[z]{polname or polynomial expression} @@ -1294,17 +1291,19 @@ Syntax: ``\PolTypesetCmdPrefix{}`` .. _PolTypeset*: -``\PolTypeset*{}`` -~~~~~~~~~~~~~~~~~~ +``\PolTypeset*[]{}`` +~~~~~~~~~~~~~~~~~~~~ -Syntax: ``\PolTypeset*{}`` +Syntax: ``\PolTypeset*[]{}`` - Typesets in ascending powers. Use ``[]`` optional argument - (after the ``*``) to use another letter than ``x``. + Typesets in ascending powers. The ```` optional argument + (after the ``*``) declares the letter to use in the *output*. + As for `\\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{}{}`` .. 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: ```` and ````. + The declaration of the ``S_k``\ 's will overwrite with no warning + previously declared polynomials with identical names ``S_k``, + i.e. ``_k``. This is why the macro was designed + to expect two names: ```` and ````. 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 - `_ creates variables sharing - the ```` 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 `_ + creates xintexpr_ variables whose names start with + ``L_``, ``R_``, and ``Z_``, also + ``M_`` for holding the multiplicities, and this may + overwrite pre-existing user-defined xintexpr_ variables. .. warning:: @@ -2300,7 +2302,9 @@ Syntax: ``\PolToExpr{}`` ^^^^^^^^^^^^^^^^^^^ 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 `_ macro to safe values prior to grab the polynomial expression up to the terminator -- cgit v1.2.3