diff options
author | Norbert Preining <norbert@preining.info> | 2022-05-20 03:01:51 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2022-05-20 03:01:51 +0000 |
commit | 33fe673e1a4a678f76e23a91da0f449998af9c47 (patch) | |
tree | 54a9486c6ec7621c31e33af6e6f111666585b56a /macros/generic/polexpr/polexpr-ref.rst.txt | |
parent | 049d8c10a2be69e330d26efa5116b5ec451b8eab (diff) |
CTAN sync 202205200301
Diffstat (limited to 'macros/generic/polexpr/polexpr-ref.rst.txt')
-rw-r--r-- | macros/generic/polexpr/polexpr-ref.rst.txt | 106 |
1 files changed, 57 insertions, 49 deletions
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{<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 |