as for Calc and the math library

[Christopher Dimech <dimech@gmx.com>]

> Sent: Monday, August 12, 2024 at 6:52 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Ihor Radchenko" <yantar92@posteo.net>
> Cc: incal@dataswamp.org, emacs-devel@gnu.org
> Subject: Re: as for Calc and the math library
>
> > From: Ihor Radchenko <yantar92@posteo.net>
> > Cc: incal@dataswamp.org, emacs-devel@gnu.org
> > Date: Sun, 11 Aug 2024 18:27:16 +0000
> >
> > Eli Zaretskii <eliz@gnu.org> writes:
> >
> > >> 1. Documenting some Calc data structures
> > >> 2. Possibly refactoring some Calc functions to use simpler API.
> > >>
> > >> It would be a much easier task and can improve the existing
> > >> functionality.
> > >
> > > I don't think I understand well enough what will this entail in
> > > practice.  Can you show an example of doing this for a couple of
> > > functions?
> >
> > For (1), I was referring to ";;;; Arithmetic routines." in
> > calc.el.
>
> (1) is documentation of Calc data structures.  If you mean the large
> commentary that describes the various form of objects that Calc can
> handle, then what is left to document?
>
> > Now, people must simply know the internal format of special
> > number representations to work with Calc from Elisp.
> > It might be worth (a) putting them into a proper manual (some kind of
> > Calc Lisp API description); (b) maybe creating constructor functions to
> > abstract the types away.
>
> Doesn't (a) already exist in the Calc manual chapter "Data Types"?
> And if not, then you are talking about enhancing the documentation of
> Calc, which is always welcome, but I fail to see how it is a step
> towards a separate library.
>
> > For (2), for starters, Calc functions often do not even have
> > docstrings. One simply has to guess(?) or read the code to understand
> > what kinds of values can be passed.
>
> And how is this relevant to (2), which is about refactoring some of
> Calc code into hopefully easier-to-use functions?

Well, if the task is focused on refactoring, then we should not change
any implementations if we are to test the results before and after, just
to be sure things are as we think should be.

> > For example, take `math-add' - no
> > docstring, and go try adding invalid arguments:
> >
> > M-: (math-add "foo" '(frac 1 2))
>
> It's a small wonder that you cannot math-add a string, especially
> since none of the objects described in the commentary are any kind of
> string.  More generally, AFAIU these don't have doc strings because
> they are internal functions.
>
> But still, I don't understand the relevance.
>
> > but somehow not
> >
> > M-: (math-add 0.1 '(frac 1 10))
> >
> > Debugger entered--Lisp error: (wrong-type-argument integer-or-marker-p 2.0)
> >   (math-gcd 2.0 10)
> >   (math-make-frac 2.0 10)
> >   (calc-add-fractions 0.1 (frac 1 10))
> >   (math-add 0.1 (frac 1 10))
>
> You again play against the rules: 0.1 is not a valid object for these
> functions.  Try
>
>   M-: (math-add '(float 1 -1) '(frac 1 10))
>
>