as for Calc and the math library

as for Calc and the math library

[Emanuel Berg]

;; __________________________________________________________
;; ``````````````````````````````````````````````````````````
;; |                         
;; 3                        CCUG-ML                        60
;;                                                          |
;; __________________________________________________________
;; `-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-`-

I have now been using the Calc library a bit!

Not a lot. Very little.

But I can already say about Calc that it is very good.
The code is good as well and as for math it is at a very
high level.

But it it is too complicated and the entry level is too high.
It is advanced math but also an advanced program.

We still need a math library that covers like up to the
introductory courses at the university. This should be
accessible with the familiar Elisp syntax.

Every function in math from school and again, maybe including
the introductory courses at the university, should be
available with Emacs notation.

So now, we don't have

(** 4 1)
( ^ 4 1)

(We do have `expt' but notation is important and should be,
for a math library, using "their" symbols and conventions,
not ours, as much as possible.)

We don't have

(defun distance-point (min max)
  (+ min (/ (- max min) 2.0)) )

Or from Logic, we don't have `nand' i.e. (not (and a b)). [last]

All that we don't have, or we do, as Calc can do it - easily.

Okay, so we don't need a new generic library. We need
a generic library which is a complement to all the basic
stuff, we don't have readily available as for now.

Out of respect for Calc there is no need to move it, now need
for that and no practical reason to.

However the new stuff must be totally transparent. When some
dude comes home from school/university and wants to try some
half-basic stuff, this should work instantly using the Elisp
he is used to. It should be "Oh, cool, Emacs has it!" And for
a long time, it should be like that for him.

If at some much later point, he (or she) moves on to "real
Calc", then he is so good we don't have to worry about
him anymore.

So we should have a CCUG-ML project: the Generic Complementary
Math Library Using Calc.

Yes, it would be to some small extent *using* Calc but to
a huge extent it would just be an interface. But 100%
transparent, so one can use Elisp and the common math
notation people know from school.

No long prefixes, no special notation, nothing, as I now know
there is _a lot_ of in Calc. People should be allowed to use
the basics of Calc without knowing it!

It should just be just like when I looked for `**' and `nand',
only this time, they should exist, thru the interface,
using Calc.

IMO!

Here is nand BTW:

(defun nand (&rest conditions)
  (when (member nil conditions)
    t) )

;; (nand)           ; nil
;; (nand 1 2 3)     ; nil
;; (nand nil)       ; t
;; (nand 1 2 nil 3) ; t

;; (not (and))           ; nil
;; (not (and 1 2 3))     ; nil
;; (not (and nil))       ; t
;; (not (and 1 2 nil 3)) ; t

And here is some Calc:

(require 'calc-ext)
(require 'cl-lib)

;; (infx "0 < 10")

(defun infx (str)
  (let* ((exp (math-read-expr str))
         (fun (car exp))
         (new (cons (intern (caar (cl-member fun math-expr-opers :key #'cadr :test #'equal)))
                    (cdr exp))))
    (apply (car new) (cdr new))))

-- 
underground experts united
https://dataswamp.org/~incal

Re: as for Calc and the math library

[Eli Zaretskii]

> From: Emanuel Berg <incal@dataswamp.org>
> Date: Sun, 11 Aug 2024 00:48:13 +0200
> 
> We don't have
> 
> (defun distance-point (min max)
>   (+ min (/ (- max min) 2.0)) )

Once again, if we want this and other functions for a math library in
Emacs, we should make sure the algorithms used are solid and stable,
and in particular don't cause errors unless the result really cannot
be expressed as a valid number.  For example, in the above, the
expression (- min max) could overflow when min/2 - max/2 that it
calculates is a valid number.

If Emacs is to have a math library, the library must use high-quality
mathematical and numerical algorithms that are well-known and
described in many textbooks on this subject matter.  This high quality
should start from the simplest calculations, and go all the way to the
most complex ones.  For example, even summing many float values
naïvely will eventually lose accuracy.  E.g., try adding 10 values of
1e-16 followed by the value of 1, that is

  (+ 1.0 1.e-16 1.e-16 1.e-16 1.e-16 1.e-16 1.e-16 1.e-16 1.e-16 1.e-16 1.e-16)

Doing this naïvely will lose all the small values, as if they were not
there at all.  So even such seemingly-simple operations might need
non-trivial algorithm to avoid losing accuracy when it could be kept.

Re: as for Calc and the math library

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

> If Emacs is to have a math library, the library must use high-quality
> mathematical and numerical algorithms that are well-known and
> described in many textbooks on this subject matter...

I agree with this point, but I suspect that writing such a library from
scratch might be a bit difficult.

May I suggest an alternative: abstract out GNU Calc math routines to be
available from Elisp without having to read Calc sources.
Such a task would require:
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.

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

as for Calc and the math library

[Christopher Dimech]

> Sent: Monday, August 12, 2024 at 4:45 AM
> From: "Ihor Radchenko" <yantar92@posteo.net>
> To: "Eli Zaretskii" <eliz@gnu.org>
> Cc: "Emanuel Berg" <incal@dataswamp.org>, emacs-devel@gnu.org
> Subject: Re: as for Calc and the math library
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> > If Emacs is to have a math library, the library must use high-quality
> > mathematical and numerical algorithms that are well-known and
> > described in many textbooks on this subject matter...
>
> I agree with this point, but I suspect that writing such a library from
> scratch might be a bit difficult.
>
> May I suggest an alternative: abstract out GNU Calc math routines to be
> available from Elisp without having to read Calc sources.
> Such a task would require:
> 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.  - Ihor Radchenko

That would be my recommendation.  Calc already offer robust mathematical
routines.  Doing a mathematical library is not difficult but required focus
and the ability to deal with complicated implementation, not just applying
direct solutions.

Re: as for Calc and the math library

[Emanuel Berg]

Ihor Radchenko wrote:

> I suspect that writing such a library from scratch might be
> a bit difficult.
>
> May I suggest an alternative: abstract out GNU Calc math
> routines to be available from Elisp without having to read
> Calc sources. Such a task would require:
;
> 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.

Very smart suggestion.

-- 
underground experts united
https://dataswamp.org/~incal

Re: as for Calc and the math library

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: Emanuel Berg <incal@dataswamp.org>, emacs-devel@gnu.org
> Date: Sun, 11 Aug 2024 16:45:54 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > If Emacs is to have a math library, the library must use high-quality
> > mathematical and numerical algorithms that are well-known and
> > described in many textbooks on this subject matter...
> 
> I agree with this point, but I suspect that writing such a library from
> scratch might be a bit difficult.

It depends on the scope and the person who'd like to work on that.

> May I suggest an alternative: abstract out GNU Calc math routines to be
> available from Elisp without having to read Calc sources.
> Such a task would require:
> 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?

In any case, this job, as any other job in Emacs, needs its
volunteer(s).  Until we have such volunteers, it's all academic.

as for Calc and the math library

[Christopher Dimech]

> Sent: Monday, August 12, 2024 at 5:59 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: Emanuel Berg <incal@dataswamp.org>, emacs-devel@gnu.org
> > Date: Sun, 11 Aug 2024 16:45:54 +0000
> >
> > Eli Zaretskii <eliz@gnu.org> writes:
> >
> > > If Emacs is to have a math library, the library must use high-quality
> > > mathematical and numerical algorithms that are well-known and
> > > described in many textbooks on this subject matter...
> >
> > I agree with this point, but I suspect that writing such a library from
> > scratch might be a bit difficult.
>
> It depends on the scope and the person who'd like to work on that.
>
> > May I suggest an alternative: abstract out GNU Calc math routines to be
> > available from Elisp without having to read Calc sources.
> > Such a task would require:
> > 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?
>
> In any case, this job, as any other job in Emacs, needs its
> volunteer(s).  Until we have such volunteers, it's all academic.

For good mathematical libraries, you require a practicing applied
mathematician.  A programmer is not enough.

Re: as for Calc and the math library

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: Ihor Radchenko <yantar92@posteo.net>, incal@dataswamp.org,
>  emacs-devel@gnu.org
> Date: Sun, 11 Aug 2024 20:17:48 +0200
> 
> For good mathematical libraries, you require a practicing applied
> mathematician.  A programmer is not enough.

That's not true.  A programmer experienced in numerical computations
is more than enough, because the relevant algorithms are known and
described in the literature, so there's no need to invent them.

as for Calc and the math library

[Christopher Dimech]

> Sent: Monday, August 12, 2024 at 6:32 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: yantar92@posteo.net, incal@dataswamp.org, emacs-devel@gnu.org
> Subject: Re: as for Calc and the math library
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: Ihor Radchenko <yantar92@posteo.net>, incal@dataswamp.org,
> >  emacs-devel@gnu.org
> > Date: Sun, 11 Aug 2024 20:17:48 +0200
> >
> > For good mathematical libraries, you require a practicing applied
> > mathematician.  A programmer is not enough.
>
> That's not true.  A programmer experienced in numerical computations
> is more than enough, because the relevant algorithms are known and
> described in the literature, so there's no need to invent them.

A mathematician can usually do better than the standard techniques.
Some descriptions in the literature can be quite old and not so up
to date.  Most of the original fortran routines was not done by programmers.

Re: as for Calc and the math library

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> > If Emacs is to have a math library, the library must use high-quality
>> > mathematical and numerical algorithms that are well-known and
>> > described in many textbooks on this subject matter...
>> 
>> I agree with this point, but I suspect that writing such a library from
>> scratch might be a bit difficult.
>
> It depends on the scope and the person who'd like to work on that.

Yes, of course. If somebody is up to writing a serious math lib, it
would be better. But having a bit simpler task idea can increase the pool
of potential volunteers.

>> May I suggest an alternative: abstract out GNU Calc math routines to be
>> available from Elisp without having to read Calc sources.
>> Such a task would require:
>> 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. 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.

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. For example, take `math-add' - no
docstring, and go try adding invalid arguments:

M-: (math-add "foo" '(frac 1 2))

Debugger entered--Lisp error: (wrong-type-argument number-or-marker-p "foo")
  (math-mul "foo" 2)
  (calc-add-fractions "foo" (frac 1 2))
  (math-add "foo" (frac 1 2))

The error checking could be improved, especially since it is a
polymorphic function that is capable of doing things like

(math-add '(vec (frac 1 2) 3 1) '(frac 1 2)) ; => (vec 1 (frac 7 2) (frac 3 2))

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

> In any case, this job, as any other job in Emacs, needs its
> volunteer(s).  Until we have such volunteers, it's all academic.

Yes, of course. I was hoping that Emanual (who is apparently interested
in this topic, or at least in improving Elisp) can be the one.

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

Re: as for Calc and the math library

[Emanuel Berg]

Ihor Radchenko wrote:

> Yes, of course. I was hoping that Emanual (who is apparently
> interested in this topic, or at least in improving Elisp)
> can be the one.

Thanks for that but after the controversy I lost the
enthusiasm just a little bit since that was very unpleasant,
but it is all good because now my own programming ideas keep
me busy instead!

You need to reach out to the young guys studying math at
universities today, one thinks all they do all day is math but
almost _all_ of them are into computers as well, how many will
use Emacs I don't know but this is the person you want for
this job :)

-- 
underground experts united
https://dataswamp.org/~incal

New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Ihor Radchenko]

Emanuel Berg <incal@dataswamp.org> writes:

> Ihor Radchenko wrote:
>
>> Yes, of course. I was hoping that Emanual (who is apparently
>> interested in this topic, or at least in improving Elisp)
>> can be the one.
> ...
> You need to reach out to the young guys studying math at
> universities today, one thinks all they do all day is math but
> almost _all_ of them are into computers as well, how many will
> use Emacs I don't know but this is the person you want for
> this job :)

Hmm. This reminds me of Google Summer of Code.
Eli, have you considered using GSC to get volunteers for implementing
some moderately difficult Emacs features? Since GSC provides financial
incentive, it may be possible to get student volunteers.

Of course, someone still needs to mentor the students, but that's less
effort compared to actually writing all the code.

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Mon, 12 Aug 2024 06:28:21 +0000
> 
> Hmm. This reminds me of Google Summer of Code.
> Eli, have you considered using GSC to get volunteers for implementing
> some moderately difficult Emacs features? Since GSC provides financial
> incentive, it may be possible to get student volunteers.
> 
> Of course, someone still needs to mentor the students, but that's less
> effort compared to actually writing all the code.

People, including the other co-maintainers, are welcome to pursue
this, but I personally have no free time or resources to do that.

I can only say that it would be harder for a casual contributor to do
a GSoC-style job for Emacs than for other projects, because Emacs has
a lot of specialized needs and requirements that take time to learn.
But maybe this is not an obstacle.

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Joel Reicher]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Ihor Radchenko <yantar92@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Mon, 12 Aug 2024 06:28:21 +0000
>>
>> Hmm. This reminds me of Google Summer of Code.
>> Eli, have you considered using GSC to get volunteers for 
>> implementing some moderately difficult Emacs features? Since 
>> GSC provides financial incentive, it may be possible to get 
>> student volunteers.
>
> I can only say that it would be harder for a casual contributor 
> to do a GSoC-style job for Emacs than for other projects, 
> because Emacs has a lot of specialized needs and requirements 
> that take time to learn.  But maybe this is not an obstacle.

Does GSC have an 'avenue' for working on bugfixes rather than 
features?

I know that's not where this thread started, and it's 
significantly less glamorous, but the requirements for a bugfix 
tend to be more immediately clear than a 'library'.

Regards,

        - Joel

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Ihor Radchenko]

Joel Reicher <joel.reicher@gmail.com> writes:

>>> Eli, have you considered using GSC to get volunteers for 
>>> implementing some moderately difficult Emacs features? Since 
>>> GSC provides financial incentive, it may be possible to get 
>>> student volunteers.
>>
>> I can only say that it would be harder for a casual contributor 
>> to do a GSoC-style job for Emacs than for other projects, 
>> because Emacs has a lot of specialized needs and requirements 
>> that take time to learn.  But maybe this is not an obstacle.
>
> Does GSC have an 'avenue' for working on bugfixes rather than 
> features?

AFAIK, no. It is based on well-defined projects.
Some nontrivial bugfixes may be worth a whole project, but I doubt that
having a goal like "close N bugs" will qualify.

> I know that's not where this thread started, and it's 
> significantly less glamorous, but the requirements for a bugfix 
> tend to be more immediately clear than a 'library'.

If we aim for volunteers to fix bugs, it should probably be some other
funding scheme; not GSoC. I am not aware about anything existing.
The only somewhat relevant thing I recall was crowdfunding scheme like
code bounty (proposed in the past on the list), but that is also more
suitable for new features.

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Pedro]

[-- Attachment #1.1.1: Type: text/plain, Size: 886 bytes --]

On 2024-08-12 20:59, Ihor Radchenko wrote:
> Joel Reicher <joel.reicher@gmail.com> writes:
>
> (...)
>
>> I know that's not where this thread started, and it's
>> significantly less glamorous, but the requirements for a bugfix
>> tend to be more immediately clear than a 'library'.
> If we aim for volunteers to fix bugs, it should probably be some other
> funding scheme; not GSoC. I am not aware about anything existing.
> The only somewhat relevant thing I recall was crowdfunding scheme like
> code bounty (proposed in the past on the list), but that is also more
> suitable for new features.

Let me share these links, if it helps to fund specific emacs stuff

- https://www.sovereigntechfund.de/programs
- https://www.sovereigntechfund.de/programs/applications
- 
https://docs.opentech.fund/otf-application-guidebook/appendix-iv-alternative-sources-of-support

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 3323 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 495 bytes --]

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Ihor Radchenko]

Pedro <pinmacs@cas.cat> writes:

>> If we aim for volunteers to fix bugs, it should probably be some other
>> funding scheme; not GSoC. I am not aware about anything existing.
>> The only somewhat relevant thing I recall was crowdfunding scheme like
>> code bounty (proposed in the past on the list), but that is also more
>> suitable for new features.
>
> Let me share these links, if it helps to fund specific emacs stuff
>
> - https://www.sovereigntechfund.de/programs
> - https://www.sovereigntechfund.de/programs/applications

This looks interesting, but I am afraid that Emacs may not exactly
qualify to fit their mission.

I am looking at https://www.sovereigntechfund.de/programs/applications,
and they write

    The Sovereign Tech Fund invests in open digital base technologies
    that are vital to the development of other software or enable
    digital networking. We invest in projects that benefit and
    strengthen the open source ecosystem. Examples include libraries for
    programming languages, package managers, open implementations of
    communication protocols, administration tools for developers,
    digital encryption technologies,...
    
    We are currently not looking for user-facing applications, such as
                     ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
    messaging apps or file storage services. If this changes, we will
    announce it here.

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Ihor Radchenko]

Pedro <pinmacs@cas.cat> writes:

> Let me share these links, if it helps to fund specific emacs stuff
> ...
> - 
> https://docs.opentech.fund/otf-application-guidebook/appendix-iv-alternative-sources-of-support

I reviewed this one.
I can only see a single fund that might be relevant - Microsoft
FOSS. (Please correct me if I missed something)

However, Microsoft FOSS is not application-based - Microsoft employees
choose. They also link to a couple of funds from other companies that
work in similar ways.

I guess that it is technically possible to participate if we somehow
spread the word to relevant company employees that Emacs could make use of
such a fund. Here is a list of links with several companies running
FOSS funds based on employee selection:
- https://github.com/microsoft/foss-fund
- https://engineering.salesforce.com/announcing-the-first-foss-contributor-fund-recipient-60a295201497/
- https://fossfunders.com/ (this one looks promising, but also
  suspicious - not much info on their website, no rules, just "contact
  us privately")

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Eli, have you considered using GSC to get volunteers for implementing
>> some moderately difficult Emacs features? Since GSC provides financial
>> incentive, it may be possible to get student volunteers.
>> 
>> Of course, someone still needs to mentor the students, but that's less
>> effort compared to actually writing all the code.

> I can only say that it would be harder for a casual contributor to do
> a GSoC-style job for Emacs than for other projects, because Emacs has
> a lot of specialized needs and requirements that take time to learn.
> But maybe this is not an obstacle.

May you elaborate?
The interested students will likely also be at least casual Emacs users.
So, some degree of familiarity is expected.
Other than that, how is Emacs dramatically different from working with
any other large codebase?

> People, including the other co-maintainers, are welcome to pursue
> this, but I personally have no free time or resources to do that.

Adding Stefan and Andrea to CC.

To add more details, FSF/GNU qualifies as a valid mentor organization
for GSoC. Org mode project even participated in it in the past:
https://orgmode.org/worg/archive/gsoc2012/orgmode-gsoc2012-ideas.html
AFAIR, there was a request from GNU this spring to submit proposals.

So, what I am talking about is not a theoretical idea. It can be done.

What is needed is a formulation of projects/features that are desired.
Mentors do not have to be maintainers. Experienced Emacs contributors
can be the mentors (also, mentoring a student can be a good addition to
some types of CVs).

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Andrea Corallo]

Ihor Radchenko <yantar92@posteo.net> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Eli, have you considered using GSC to get volunteers for implementing
>>> some moderately difficult Emacs features? Since GSC provides financial
>>> incentive, it may be possible to get student volunteers.
>>> 
>>> Of course, someone still needs to mentor the students, but that's less
>>> effort compared to actually writing all the code.
>
>> I can only say that it would be harder for a casual contributor to do
>> a GSoC-style job for Emacs than for other projects, because Emacs has
>> a lot of specialized needs and requirements that take time to learn.
>> But maybe this is not an obstacle.
>
> May you elaborate?
> The interested students will likely also be at least casual Emacs users.
> So, some degree of familiarity is expected.
> Other than that, how is Emacs dramatically different from working with
> any other large codebase?
>
>> People, including the other co-maintainers, are welcome to pursue
>> this, but I personally have no free time or resources to do that.
>
> Adding Stefan and Andrea to CC.
>
> To add more details, FSF/GNU qualifies as a valid mentor organization
> for GSoC. Org mode project even participated in it in the past:
> https://orgmode.org/worg/archive/gsoc2012/orgmode-gsoc2012-ideas.html
> AFAIR, there was a request from GNU this spring to submit proposals.
>
> So, what I am talking about is not a theoretical idea. It can be done.
>
> What is needed is a formulation of projects/features that are desired.
> Mentors do not have to be maintainers. Experienced Emacs contributors
> can be the mentors (also, mentoring a student can be a good addition to
> some types of CVs).

I think I could propose something related improving the native compiler
why not.

But I'm no expert of the GSoC, what is the typical deadline?

Also, a source of topics to work on could be our TODO, it's really full
of interesting things that needs man power (ex the paragraph "Emacs as
word processor").

Thanks

  Andrea

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Ihor Radchenko]

Andrea Corallo <acorallo@gnu.org> writes:

> I think I could propose something related improving the native compiler
> why not.

That would be welcome!

> But I'm no expert of the GSoC, what is the typical deadline?

Not this year. This year GSoC is ongoing.
Here is the timeline:
https://developers.google.com/open-source/gsoc/timeline

I presume that next year should be similar. So, expect ~ end of March
next year.

For mentors, the timeline will be May-September (with May dedicated to
getting to know each other, not actual work). In other words, summer.

> Also, a source of topics to work on could be our TODO, it's really full
> of interesting things that needs man power (ex the paragraph "Emacs as
> word processor").

I'm afraid that "Emacs as word processor" is a bit too much for
_students_ within 3 months timeline. Many other todo entries should be
suitable though.

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org, Stefan Kangas
>  <stefankangas@gmail.com>
> Date: Sun, 18 Aug 2024 11:48:17 +0000
> 
> Andrea Corallo <acorallo@gnu.org> writes:
> 
> > Also, a source of topics to work on could be our TODO, it's really full
> > of interesting things that needs man power (ex the paragraph "Emacs as
> > word processor").
> 
> I'm afraid that "Emacs as word processor" is a bit too much for
> _students_ within 3 months timeline.

That paragraph includes 20 separate tasks.  They could be performed
one by one, not necessarily all of them together.  At least some of
them are definitely suitable for GSoC type jobs.  For example, "import
/ export RTF files".

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> I'm afraid that "Emacs as word processor" is a bit too much for
>> _students_ within 3 months timeline.
>
> That paragraph includes 20 separate tasks.  They could be performed
> one by one, not necessarily all of them together.  At least some of
> them are definitely suitable for GSoC type jobs.  For example, "import
> / export RTF files".

Doesn't it require completing a couple of display-engine related
features like flowing text around images? Or does import/export imply
something else, not _displaying_ and editing RTF document?

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes)

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com
> Date: Sun, 18 Aug 2024 12:52:22 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> I'm afraid that "Emacs as word processor" is a bit too much for
> >> _students_ within 3 months timeline.
> >
> > That paragraph includes 20 separate tasks.  They could be performed
> > one by one, not necessarily all of them together.  At least some of
> > them are definitely suitable for GSoC type jobs.  For example, "import
> > / export RTF files".
> 
> Doesn't it require completing a couple of display-engine related
> features like flowing text around images? Or does import/export imply
> something else, not _displaying_ and editing RTF document?

Determining what it means and where it ends is IMO part of the job.
The ability to import RTF files will be a very useful feature even if
it doesn't support images at first.  (And what exactly is a problem
with supporting images, given that Emacs is already capable of
displaying them?)

RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> > That paragraph includes 20 separate tasks.  They could be performed
>> > one by one, not necessarily all of them together.  At least some of
>> > them are definitely suitable for GSoC type jobs.  For example, "import
>> > / export RTF files".
>> 
>> Doesn't it require completing a couple of display-engine related
>> features like flowing text around images? Or does import/export imply
>> something else, not _displaying_ and editing RTF document?
>
> Determining what it means and where it ends is IMO part of the job.
> The ability to import RTF files will be a very useful feature even if
> it doesn't support images at first.

Then, it is indeed doable.
If we limit features to current display engine capabilities, simply
something like libpandoc will be good enough for basic import/export
(not just RTF, but a plethora of other formats as well).

> ... (And what exactly is a problem
> with supporting images, given that Emacs is already capable of
> displaying them?)

Some text flowing around the images
....	 ...  with multiple lines of text
   ....	   ....	    . going beside the
  .		.    . image.
  . ....	.     .
    .	   ..  ..     .
    ..	    .....      .
     .........	 ...   .
            ..	    ..

Or text and image displayed on top of each other.

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

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com
> Date: Sun, 18 Aug 2024 13:56:46 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Determining what it means and where it ends is IMO part of the job.
> > The ability to import RTF files will be a very useful feature even if
> > it doesn't support images at first.
> 
> Then, it is indeed doable.
> If we limit features to current display engine capabilities, simply
> something like libpandoc will be good enough for basic import/export
> (not just RTF, but a plethora of other formats as well).

The job, as I see it, is to decode the RTF format and convert its
typeface information into Emacs faces.

> > ... (And what exactly is a problem
> > with supporting images, given that Emacs is already capable of
> > displaying them?)
> 
> Some text flowing around the images
> ....	 ...  with multiple lines of text
>    ....	   ....	    . going beside the
>   .		.    . image.
>   . ....	.     .
>     .	   ..  ..     .
>     ..	    .....      .
>      .........	 ...   .
>             ..	    ..
> 
> Or text and image displayed on top of each other.

We aren't afraid of that in EWW and shr.el, are we?  We could use the
same technique here.

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> If we limit features to current display engine capabilities, simply
>> something like libpandoc will be good enough for basic import/export
>> (not just RTF, but a plethora of other formats as well).
>
> The job, as I see it, is to decode the RTF format and convert its
> typeface information into Emacs faces.

Agree.

>> > ... (And what exactly is a problem
>> > with supporting images, given that Emacs is already capable of
>> > displaying them?)
>> 
>> Some text flowing around the images
>>  ...
>> Or text and image displayed on top of each other.
>
> We aren't afraid of that in EWW and shr.el, are we?  We could use the
> same technique here.

You mean slicing? This may work for flowing text around, but it will not
work for overlaying images and text.

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

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com
> Date: Sun, 18 Aug 2024 14:35:15 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Or text and image displayed on top of each other.
> >
> > We aren't afraid of that in EWW and shr.el, are we?  We could use the
> > same technique here.
> 
> You mean slicing? This may work for flowing text around, but it will not
> work for overlaying images and text.

Then overlaying will not be supported.  It is still a valuable
feature, IMO.

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Jim Porter]

On 8/18/2024 7:35 AM, Ihor Radchenko wrote:
>>> Some text flowing around the images
>>>   ...
>>> Or text and image displayed on top of each other.
>>
>> We aren't afraid of that in EWW and shr.el, are we?  We could use the
>> same technique here.
> 
> You mean slicing? This may work for flowing text around, but it will not
> work for overlaying images and text.

EWW/shr.el don't actually use slicing for flowing text, as far as I 
know. I suppose that could work, but I'd be worried about 
miscalculations causing the slices to be misaligned (for example if we 
tried to support the CSS 'float: right' property).

In short, EWW/shr.el's strategy for flowing text around images is to 
simply ignore it (unless I'm misunderstanding part of that code).

For RTF support, I don't know if Emacs needs to support all (or even 
most) features of RTF to still be useful. If Emacs showed images on 
their own line no matter what the RTF document requests, that's still a 
big improvement over not being able to view RTF documents at all.

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Eli Zaretskii]

> Date: Sun, 18 Aug 2024 10:37:51 -0700
> Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 8/18/2024 7:35 AM, Ihor Radchenko wrote:
> >>> Some text flowing around the images
> >>>   ...
> >>> Or text and image displayed on top of each other.
> >>
> >> We aren't afraid of that in EWW and shr.el, are we?  We could use the
> >> same technique here.
> > 
> > You mean slicing? This may work for flowing text around, but it will not
> > work for overlaying images and text.
> 
> EWW/shr.el don't actually use slicing for flowing text, as far as I 
> know. I suppose that could work, but I'd be worried about 
> miscalculations causing the slices to be misaligned (for example if we 
> tried to support the CSS 'float: right' property).

Using :align-to should allow us to align the slices horizontally (if
that is what you had in mind).

> In short, EWW/shr.el's strategy for flowing text around images is to 
> simply ignore it (unless I'm misunderstanding part of that code).

Right, and the display of RTF could do the same.

> For RTF support, I don't know if Emacs needs to support all (or even 
> most) features of RTF to still be useful. If Emacs showed images on 
> their own line no matter what the RTF document requests, that's still a 
> big improvement over not being able to view RTF documents at all.

I say let's start from the text parts: the fonts, the faces, the
indentation, the numbered and unnumbered lists, etc.  If we can pull
that out, we will already have a terrifically useful feature.

Rome wasn't built in a day.

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[Jim Porter]

On 8/18/2024 11:16 AM, Eli Zaretskii wrote:
>> Date: Sun, 18 Aug 2024 10:37:51 -0700
>> Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com
>> From: Jim Porter <jporterbugs@gmail.com>
>>
>> EWW/shr.el don't actually use slicing for flowing text, as far as I
>> know. I suppose that could work, but I'd be worried about
>> miscalculations causing the slices to be misaligned (for example if we
>> tried to support the CSS 'float: right' property).
> 
> Using :align-to should allow us to align the slices horizontally (if
> that is what you had in mind).

My worry was that if you had this,

   This is some text   [image slice]
   that goes on        [image slice]
   multiple lines.     [image slice]

we'd have to be very careful. Text-scaling is probably the biggest risk. 
If you enlarge the text, the line-height changes, which would probably 
break things (though I guess we could scale the image too).

In any case, we can cross this bridge when we get to it.

> I say let's start from the text parts: the fonts, the faces, the
> indentation, the numbered and unnumbered lists, etc.  If we can pull
> that out, we will already have a terrifically useful feature.

I agree. SHR has already implemented these[1], so it would probably be a 
good source of ideas for how to render these parts. Maybe we could even 
pull some of the code out into a common file.

[1] There's no CSS support though, so in practice, most web pages these 
days end up using the default font with SHR.

Re: RTF import/export emacs (was: New Emacs features via Google Summer of Code (or other similar stipend schemes))

[tomas]

[-- Attachment #1: Type: text/plain, Size: 1165 bytes --]

On Sun, Aug 18, 2024 at 11:38:49AM -0700, Jim Porter wrote:
> On 8/18/2024 11:16 AM, Eli Zaretskii wrote:
> > > Date: Sun, 18 Aug 2024 10:37:51 -0700
> > > Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com
> > > From: Jim Porter <jporterbugs@gmail.com>
> > > 
> > > EWW/shr.el don't actually use slicing for flowing text, as far as I
> > > know. I suppose that could work, but I'd be worried about
> > > miscalculations causing the slices to be misaligned (for example if we
> > > tried to support the CSS 'float: right' property).
> > 
> > Using :align-to should allow us to align the slices horizontally (if
> > that is what you had in mind).
> 
> My worry was that if you had this,
> 
>   This is some text   [image slice]
>   that goes on        [image slice]
>   multiple lines.     [image slice]
> 
> we'd have to be very careful. Text-scaling is probably the biggest risk. If
> you enlarge the text, the line-height changes, which would probably break
> things (though I guess we could scale the image too).

Let alone when you have lines with differing heights. Sounds like quite a bit
of fun :-)

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-devel@gnu.org, Stefan Kangas <stefankangas@gmail.com>, Andrea
>  Corallo <acorallo@gnu.org>
> Date: Mon, 12 Aug 2024 19:17:05 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Eli, have you considered using GSC to get volunteers for implementing
> >> some moderately difficult Emacs features? Since GSC provides financial
> >> incentive, it may be possible to get student volunteers.
> >> 
> >> Of course, someone still needs to mentor the students, but that's less
> >> effort compared to actually writing all the code.
> 
> > I can only say that it would be harder for a casual contributor to do
> > a GSoC-style job for Emacs than for other projects, because Emacs has
> > a lot of specialized needs and requirements that take time to learn.
> > But maybe this is not an obstacle.
> 
> May you elaborate?

Sorry, I don't know what else to say.  I think the above is clear
enough.  Granted, it's my opinion, and others could disagree, but I
didn't write that by accident, I wrote that with full intent.

> The interested students will likely also be at least casual Emacs users.
> So, some degree of familiarity is expected.

User-level familiarity doesn't help in these matters, IME.

> Other than that, how is Emacs dramatically different from working with
> any other large codebase?

In a nutshell, Emacs is much larger than most other projects, and its
features are much less localized than those of other large projects.

> So, what I am talking about is not a theoretical idea. It can be done.

I didn't say it couldn't be done.

> What is needed is a formulation of projects/features that are desired.
> Mentors do not have to be maintainers. Experienced Emacs contributors
> can be the mentors (also, mentoring a student can be a good addition to
> some types of CVs).

We have etc/TODO which could be used as a source of ideas.

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> The interested students will likely also be at least casual Emacs users.
>> So, some degree of familiarity is expected.
>
> User-level familiarity doesn't help in these matters, IME.

>> Other than that, how is Emacs dramatically different from working with
>> any other large codebase?
>
> In a nutshell, Emacs is much larger than most other projects, and its
> features are much less localized than those of other large projects.

But not every feature, right? Some parts are easier to hack than others.
I imagine that many Elisp parts are somewhat easier compared to C code.

>> What is needed is a formulation of projects/features that are desired.
>> Mentors do not have to be maintainers. Experienced Emacs contributors
>> can be the mentors (also, mentoring a student can be a good addition to
>> some types of CVs).
>
> We have etc/TODO which could be used as a source of ideas.

Are there any specific todo items there that you view as more suitable
for people with limited experience in Emacs codebase?

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

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-devel@gnu.org, stefankangas@gmail.com, acorallo@gnu.org
> Date: Sun, 18 Aug 2024 11:09:54 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> The interested students will likely also be at least casual Emacs users.
> >> So, some degree of familiarity is expected.
> >
> > User-level familiarity doesn't help in these matters, IME.
> 
> >> Other than that, how is Emacs dramatically different from working with
> >> any other large codebase?
> >
> > In a nutshell, Emacs is much larger than most other projects, and its
> > features are much less localized than those of other large projects.
> 
> But not every feature, right? Some parts are easier to hack than others.
> I imagine that many Elisp parts are somewhat easier compared to C code.

Only if you are lucky, and only if you are familiar with the code in
question.

> >> What is needed is a formulation of projects/features that are desired.
> >> Mentors do not have to be maintainers. Experienced Emacs contributors
> >> can be the mentors (also, mentoring a student can be a good addition to
> >> some types of CVs).
> >
> > We have etc/TODO which could be used as a source of ideas.
> 
> Are there any specific todo items there that you view as more suitable
> for people with limited experience in Emacs codebase?

Possibly, but someone needs to look at them with this in mind.

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Stefan Kangas]

Ihor Radchenko <yantar92@posteo.net> writes:

>> We have etc/TODO which could be used as a source of ideas.
>
> Are there any specific todo items there that you view as more suitable
> for people with limited experience in Emacs codebase?

I agree with many of the reservations Eli has, but on the other hand
this depends highly on what the projects will be.  Perhaps this could be
a good way to attract new contributors, some of which will be found in
the already existing Emacs community (parts of which do not interact
much with emacs-devel).

So I'm basically all in favor of GSoC, but someone needs to do the work
to get the ball rolling, for example with regards to suitable proposals.
If someone were to propose a list of projects, then it would be easier
for others to comment on it.  This could potentially also be used to
expand the text that is currently in etc/TODO, to improve that file.
If that's possible, the effort will never be wasted.

Another thing that would be useful in this regard is if people could
indicate their interest in mentoring students, even tentatively.
As for me, I _might_ have the time to act as mentor, but that is highly
tentative as I didn't consider or think about that very closely.  It
would also depend on the project idea, of course.

Re: New Emacs features via Google Summer of Code (or other similar stipend schemes) (was: as for Calc and the math library)

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>>> We have etc/TODO which could be used as a source of ideas.
>>
>> Are there any specific todo items there that you view as more suitable
>> for people with limited experience in Emacs codebase?
>
> I agree with many of the reservations Eli has, but on the other hand
> this depends highly on what the projects will be.  Perhaps this could be
> a good way to attract new contributors, some of which will be found in
> the already existing Emacs community (parts of which do not interact
> much with emacs-devel).

Yup. I want to have some kind of shortlist of tasks that the
maintainers familiar with the code can suggest as student projects.

Then, we can eventually go out to reddit/mastodon/reach Sacha
Chua/Emacsconf to ask the community.

> So I'm basically all in favor of GSoC, but someone needs to do the work
> to get the ball rolling, for example with regards to suitable proposals.
> If someone were to propose a list of projects, then it would be easier
> for others to comment on it.  This could potentially also be used to
> expand the text that is currently in etc/TODO, to improve that file.
> If that's possible, the effort will never be wasted.

+1

> Another thing that would be useful in this regard is if people could
> indicate their interest in mentoring students, even tentatively.
> As for me, I _might_ have the time to act as mentor, but that is highly
> tentative as I didn't consider or think about that very closely.  It
> would also depend on the project idea, of course.

I am also considering mentoring, but that will be for Org mode.

I think that it is a good idea to shortlist things from TODO file before
asking potential mentors. Simply to prioritize projects that are deemed
important by the maintainers.

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

Re: as for Calc and the math library

[Eli Zaretskii]

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

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

Re: as for Calc and the math library

[Ihor Radchenko]

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>

Re: as for Calc and the math library

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: incal@dataswamp.org, emacs-devel@gnu.org
> Date: Sun, 11 Aug 2024 19:13:16 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > 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.

I think if someone will step forward to do this kind of job, it will
be up to them what steps should lead to the goal.

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

For internal functions that don't expect to see objects other than
what they were designed to handle?  Nice error messages are for the
application level, not for this level, IMO.

as for Calc and the math library

[Christopher Dimech]

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