Re: as for Calc and the math library

[Ihor Radchenko <yantar92@posteo.net>]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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?

Put this commentary, and other relevant APIs into .texi, explained and
organized aiming for Elisp API users.

>> 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"?

Hmm. Yes. Last time, I failed to see them.

> 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.

The idea is to have a description and overview of what the library
does. It will make the design easier later.

>> 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?

If these functions are going to be used from Elisp, they must have
docstrings.

>> 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.

I meant this function as a candidate for math library we are
discussing.

>> 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))

My point is that the error message could be nicer.
Something like (wrong-type-argument calc-value-p 2.0)
"integer-or-marker-p" creates an impression that you can only pass
integers there.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>