poormanlog (0.08final, 2026/11/01)
==================================

Description: "log and exp with almost 9 digits"

poormanlog.tex served since 2019 as a bootstrap for xintlog.sty.
But xint release 2.0a1 (2026/11/01) has no use for it anymore.
It is now frozen and will not get any updates in the future.

Manifest:

    Both poormanlog.tex and poormanlog.sty should go into
    tex/generic/poormanlog/


TOC:
- Usage
- Interface
- History
- More details
- Changes
- Conditions of distribution, License


Usage
-----

poormanlog can be used with Plain e-TeX (\input poormanlog) and
presumably other formats, as well as with LaTeX for which the
usual interface (\usepackage{poormanlog}) is provided.


Interface
---------

The package provides two expandable macros: \PMLogZ and \PMPowTen.
The Z in \PMLogZ refers to the fact that the output of \PMLogZ may
have leading zeros.

- \PMLogZ{<d_1d_2...d_9>} computes base 10 logarithms
  of numbers between 1 and 10: the input of exactly 9 digits
  stands for d_1.d_2d_3...d_9 and d_1 must be > 0.
  The output consists of nine digits x_1x_2....x_9 such that

      log10(d_1.d_2d_3...d_9) \approx 0.x_1x_2....x_9.

  (see below about what happens if input is 999999999).

  (Z in the name is because output may have leading zeros)

- \PMPowTen{<x_1x_2...x_9>} computes 10 to the power X where
  X= 0.x_1x_2....x_9. (thus, only non-negative).

  The output consists of nine digits d_1d_2...d_9 such that

      10^X \approx d_1.d_2...d_9.

In both cases, the precision is a bit less than 9 fixed-point digits.

History
-------

This package was produced in 2019 as a temporary clutch in 2019
when xintexpr had incorporated trigonometric functions, but did
not yet have logarithm and exponential.  Later, in 2021, it
provided the bootstrapping for xint to provide logarithms and
exponentials up to 62 digits.

It implements a Cordix type approch to 10^x. It does that without
the benefit of an extra layer on \numexpr, only exploiting to the
fullest "scaling" operations a*b/c where a*b is authorized but the
final (rounded) a*b/c must obey TeX bound.

It turns out this is sub-optimal.  It is better to first develop
means, using \numexpr, to do exact operations on say 8digits
integers, than to insist on solving everything using only \numexpr
scaling operations.  This became very obvious to this author in
March 2026, when he used loads of ingenuity to implement modular
exponentiation using only \numexpr and no use of numbers beyond
the TeX bound (and no pairs of such).  And in the end, the code,
very clever and highly optimized proved five times less efficient
than simply using for modular exponentiation the high-level xint
interface given as an example in the xint user manual!

This experience motivated the author to drop the poormanlog
approach It was silly for xint-bootstrapping for another reason:
it targeted not much worse than 1ulp error at P=9, but was used
only to get 6 digits.  And there was a third bad aspect: it
provided a model for xintlog to use tables of values of 10^x,
which caused it to employ long-multiplication, whereas in the
2.0a1 release, only additions and multiplications by small
multiplicands are needed.


More details
------------

\PMLogZ{#1} computes base-10 logarithms:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

expansion: the argument is submitted to f-expansion and the macro
           itself expands fully in two steps.

input:  #1 must be (or f-expands to) a mantissa ddddddddd with exactly
        nine digits, standing for D = d.dddddddd, 1 <= D < 10

output: nine digits xxxxxxxxx standing for X = 0.xxxxxxxxx such that
        log10(D) is about X

        CAUTION: for #1=999999999, the macro outputs 000000000,
        which are the fractional digits of the correct rounding
        1.000000000 of log10(9.99999999)=0.9999999995657...

precision: It seems from testing that absolute error is not much
           more than 1 unit in the last (*fixed point*) place,
           and result differs from rounded mathematical value of
           log10(D) by at most 1 unit in the last place.
              (*attention estimate not rigorously proven*).


\PMPowTen{#1} computes fractional powers of 10:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

expansion: the argument is submitted to f-expansion and the macro
           itself expands fully in two steps.

input:  #1 must be (f-expands to) exactly nine digits xxxxxxxxx, standing
        for X = 0.xxxxxxxxx

output: nine digits ddddddddd, such that D = d.dddddddd is about 10^X
        The first digit of output is never zero (i.e. 1 <= D < 10)

precision: It seems from testing that absolute error is less than
           2 units in the last place, and result D differs from
           rounded mathematical value of 10^X by at most 2 units in
           the last place.
               (*attention estimate not rigorously proven*).


Changes
-------

- 0.08final (2026/11/01)

  * replace "Caveat" section in this README by a "History" section.

  * explain it is not used by xint anymore, announce it will not be
    updated in future.

- 0.08 (2026/11/01) [not released]:

  * use some \chardef's, \mathchardef's and \count's for efficiency.

  * re-organize this README, add the "Caveat" section.

- 0.07 (2022/05/25): (again cosmetic changes)

  * add a % at end of the \ProvidesPackage line in poormanlog.sty

  * release 0.06 modified only the README and forgot to update the
    version strings in poormanlog.sty and in poormanlog.tex

- 0.06 (2021/04/21): documentation update (warning?) regarding
  \PMLogZ{999999999} output being surprisingly 000000000.

- 0.05 (2019/04/22): the additions/patches to xint originally
  provided by poormanlog.tex got moved into xint 1.3f itself.

  Thus, poormanlog now reduces to only two macros
  \PMLogZ and \PMPowTen.  It can be imported by other macro
  files with no danger of conflicting with future releases of
  xint in case of concurrent usage.

- 0.04 (2019/02/17): initial release.  The package has no
  dependencies and alongside two macros \PMLogZ and \PMPowTen
  also provides some specific additions to xint.


LICENSE
-------

Copyright (C) 2019-2022, 2026 Jean-Francois Burnol.

This Work may be distributed and/or modified under the conditions of the
LaTeX Project Public License version 1.3c. This version of this license
is in

    <http://www.latex-project.org/lppl/lppl-1-3c.txt>

and version 1.3 or later is part of all distributions of LaTeX version
2005/12/01 or later.

This Work has the LPPL maintenance status `author-maintained'.

The Author of this Work is Jean-Francois Burnol.

This Work consists of files poormanlog.tex, poormanlog.sty and this
README.
