[ELPA] New package: transient

[ELPA] New package: transient

[Jonas Bernoulli]

Hello,

I would like to add Transient [1] to GNU Elpa.  It comes with an Info
manual, which you can also read online [2].

  1: https://github.com/magit/transient
  2: https://magit.vc/manual/transient

The TL;DR is:

> Taking inspiration from prefix keys and prefix arguments, Transient
> implements a similar abstraction involving a prefix command, infix
> arguments and suffix commands. [...] When the user calls a transient
> prefix command, then a transient (temporary) keymap is activated,
> which binds the transient's infix and suffix commands, [...] The
> available suffix and infix commands and their state are shown in a
> popup buffer until the transient is exited by invoking a suffix
> command.

I admit that that is a bit technical and the manual even more so.
That obviously needs some work.  But that doesn't keep end-users from
successfully using these transient commands; Magit users already do.

Already a few third-party packages also use Transient.  It supersedes
Magit-Popup, which Magit previously used and which also has some third-
party users.  Hydra is another package that is somewhat similar.  The
manual comes with some comparisons [3].

  3: https://magit.vc/manual/transient/Related-Abstractions-and-Packages.html

Yes, this is actually a step towards adding Magit to GNU Elpa, which
some of you have asked for before, once or twice.  ;D

I have already signed copyright assignment for "Emacs".  Almost a week
ago I contacted assign@gnu.org because my new employer also needs to
sign some things.  I re-send that message today.

  Cheers,
  Jonas

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> CCing three authors who use Transient in their packages because I am
> interested in their opinions about the symbol names.
>

Thanks for including me. I think you guys covered pretty much everything
that had to be said, and I also think it's more logical if everything
related to a package starts with the same namespace, so I'd be in favor of
`transient-current-prefix`, `transient-current-command`,
`transient-define-command`, `transient-define-prefix`, etc.

Overall I think it's a shame that the Emacs api wasn't designed with
discoverability/consistency in mind, and that's why libraries like dash.el
/ seq.el are the way to go for me. I value "conventions over configuration"
principles a lot, I don't like running into design exceptions and corner
cases and having to read manuals :-)

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 1125 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Wed, 29 Apr 2020 10:29:55 +0200
> Cc: Adam Porter <adam@alphapapa.net>, Kyle Meyer <kyle@kyleam.com>,
>  Stefan Monnier <monnier@iro.umontreal.ca>
> 
> Overall I think it's a shame that the Emacs api wasn't designed with discoverability/consistency in mind

Would you mind elaborate on this deficiency?  I don't think I quite
understand the complaint.

Thanks.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > Overall I think it's a shame that the Emacs api wasn't designed with
> discoverability/consistency in mind
>
> Would you mind elaborate on this deficiency?  I don't think I quite
> understand the complaint.


It's hard to really criticize because Emacs was designed ages ago.

My point is simply this one: when I look at
https://github.com/magnars/dash.el, https://github.com/NicolasPetton/seq.el
 or https://github.com/magnars/s.el I can immediately understand how the
library works and how to achieve things. I can also easily use `C-h f` to
find about the function I want.

In Emacs, parts of it are designed following the same principle, but a lot
of it isn't:

   -
   https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
sometimes
   assoc, alist-get, assq, copy-alist. How am I supposed to use `C-h f alist
   TAB` to discover the function I want? I can't, I have to go to that webpage
   and read it all.
   -
   https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html
sometimes
   named logically (nth, remove, append), sometimes named after implementation
   detail (car, cdr), and no grouping at all so I can't `C-h f list TAB`

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 1878 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Wed, 29 Apr 2020 11:50:08 +0200
> Cc: Jonas Bernoulli <jonas@bernoul.li>, Emacs developers <emacs-devel@gnu.org>, 
> 	Adam Porter <adam@alphapapa.net>, Kyle Meyer <kyle@kyleam.com>, 
> 	Stefan Monnier <monnier@iro.umontreal.ca>
> 
> * https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes assoc,
>  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I want? I
>  can't, I have to go to that webpage and read it all.

I think "C-h d alist RET" is your friend.

> * https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html sometimes named
>  logically (nth, remove, append), sometimes named after implementation detail (car, cdr), and no grouping
>  at all so I can't `C-h f list TAB`

Also, the 'i' command in Info.

But you said you didn't want to read manuals, so I'm not sure why the
examples are from the manual.

Thanks.

Re: [ELPA] New package: transient

[tomas]

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

On Wed, Apr 29, 2020 at 01:05:30PM +0300, Eli Zaretskii wrote:
> > From: Philippe Vaucher <philippe.vaucher@gmail.com>
> > Date: Wed, 29 Apr 2020 11:50:08 +0200
> > Cc: Jonas Bernoulli <jonas@bernoul.li>, Emacs developers <emacs-devel@gnu.org>, 
> > 	Adam Porter <adam@alphapapa.net>, Kyle Meyer <kyle@kyleam.com>, 
> > 	Stefan Monnier <monnier@iro.umontreal.ca>
> > 
> > * https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes assoc,
> >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I want? I
> >  can't, I have to go to that webpage and read it all.
> 
> I think "C-h d alist RET" is your friend.

Yes, but :)

For people with some roots in Lisp culture (I'm one of them,
mind you), "alist" is obvious. It's an association list, duh.
For newcomers... not so much.

I'm all for "building bridges" rather than "obliterating
cultures", but it seems we need some ideas on how to do
that.

An interesting topic, for sure.

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Date: Wed, 29 Apr 2020 12:17:55 +0200
> From: <tomas@tuxteam.de>
> 
> > > * https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes assoc,
> > >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I want? I
> > >  can't, I have to go to that webpage and read it all.
> > 
> > I think "C-h d alist RET" is your friend.
> 
> Yes, but :)
> 
> For people with some roots in Lisp culture (I'm one of them,
> mind you), "alist" is obvious. It's an association list, duh.
> For newcomers... not so much.

I was replying to the above, where the issue is that not all of the
functions' names begin with "alist".  Evidently, this means the
"alist" obstacle was already overcome.

Re: [ELPA] New package: transient

[tomas]

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

On Wed, Apr 29, 2020 at 01:33:08PM +0300, Eli Zaretskii wrote:
> > Date: Wed, 29 Apr 2020 12:17:55 +0200
> > From: <tomas@tuxteam.de>
> > 
> > > > * https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes assoc,
> > > >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I want? I
> > > >  can't, I have to go to that webpage and read it all.
> > > 
> > > I think "C-h d alist RET" is your friend.
> > 
> > Yes, but :)
> > 
> > For people with some roots in Lisp culture (I'm one of them,
> > mind you), "alist" is obvious. It's an association list, duh.
> > For newcomers... not so much.
> 
> I was replying to the above, where the issue is that not all of the
> functions' names begin with "alist".  Evidently, this means the
> "alist" obstacle was already overcome.

In the concrete, yes. I still mull over the more general
problem (without having a good idea, unfortunately).

I just wanted to raise some awareness, since it's an
ever-recurring pattern.

Cheers
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Adam Porter]

Hi Jonas, et al,

On 4/28/20, Jonas Bernoulli <jonas@bernoul.li> wrote:
>
> CCing three authors who use Transient in their packages because I am
> interested in their opinions about the symbol names.

Thanks for considering me.  I'm generally in favor of consistent
symbol prefixes, but sometimes that leads to awkward names, so I don't
mind some exceptions.  In this case, it doesn't matter to me whether
these symbols in Transient are renamed; I could easily rename the ones
used in my package to match, so I'm happy with whatever you decide.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > *
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
> sometimes assoc,
> >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB`
> to discover the function I want? I
> >  can't, I have to go to that webpage and read it all.
>
> I think "C-h d alist RET" is your friend.
>

You miss the central point of my argument. The problem is not that the doc
is hard to find, it's that I *have* to find it to know which are the
related functions.

It is much easier for the mind to think in terms of namespaces, here are
examples from other languages:

   - https://clojure.github.io/clojure/clojure.string-api.html all string
   functions stored under string
   - http://www.cplusplus.com/reference/cstring/ almost all string
   manipulation function start with "str"
   - https://ruby-doc.org/stdlib-2.4.1/libdoc/fileutils/rdoc/FileUtils.html all
   file manipulation function are stored in FileUtils::

I could go on but I think you should be able to understand my examples.

Once related functions are namespaced together, almost all tooling benefit
from it. No need to provide a manual grouping the unrelated functions
together, just document each function:

   - autocompletion can help you guess the right function.
   - searching for function names (C-h f) can help you find the right
   function.



> > *
> https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html
> sometimes named
> >  logically (nth, remove, append), sometimes named after implementation
> detail (car, cdr), and no grouping
> >  at all so I can't `C-h f list TAB`
>
> Also, the 'i' command in Info.
>
> But you said you didn't want to read manuals, so I'm not sure why the
> examples are from the manual.


Again you strawman my argument. Try to understand my central point, and
then reply to that instead of details of "how you do it right now and that
works for you".

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 3032 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> I think "C-h d alist RET" is your friend.
>

To further illustrate my point, this doesn't lists `assq` or `assoc`, both
functions being indispensable when using alists.

Comically it mentions rassq-delete-all because its docstring has the word
"alist" but not assq.

Philippe

[-- Attachment #2: Type: text/html, Size: 562 bytes --]

Re: [ELPA] New package: transient

[Stefan Monnier]

FWIW, I completely agree with this.
Emacs's own "core" library should follow the "prefix" convention.
The resulting "structuring" of the names would help discoverability

This was a major motivation for the `seq` and `map` packages, and maybe
we should keep doing that with more things (e.g. add a `list` package
where all the list functions get a new name using the `list` prefix, or
add a `process` package were all the process related primitives are
given a "process-"prefix, ...).


        Stefan


Philippe Vaucher [2020-04-29 11:50:08] wrote:

>>
>> > Overall I think it's a shame that the Emacs api wasn't designed with
>> discoverability/consistency in mind
>>
>> Would you mind elaborate on this deficiency?  I don't think I quite
>> understand the complaint.
>
>
> It's hard to really criticize because Emacs was designed ages ago.
>
> My point is simply this one: when I look at
> https://github.com/magnars/dash.el, https://github.com/NicolasPetton/seq.el
>  or https://github.com/magnars/s.el I can immediately understand how the
> library works and how to achieve things. I can also easily use `C-h f` to
> find about the function I want.
>
> In Emacs, parts of it are designed following the same principle, but a lot
> of it isn't:
>
>    -
>    https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
> sometimes
>    assoc, alist-get, assq, copy-alist. How am I supposed to use `C-h f alist
>    TAB` to discover the function I want? I can't, I have to go to that webpage
>    and read it all.
>    -
>    https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html
> sometimes
>    named logically (nth, remove, append), sometimes named after implementation
>    detail (car, cdr), and no grouping at all so I can't `C-h f list TAB`
>
> Kind regards,
> Philippe

Re: [ELPA] New package: transient

[tomas]

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

On Wed, Apr 29, 2020 at 03:12:50PM +0200, Philippe Vaucher wrote:
> >
> > > *
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
> > sometimes assoc,
> > >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB`
> > to discover the function I want? I
> > >  can't, I have to go to that webpage and read it all.
> >
> > I think "C-h d alist RET" is your friend.
> >
> 
> You miss the central point of my argument. The problem is not that the doc
> is hard to find, it's that I *have* to find it to know which are the
> related functions.

True.

> It is much easier for the mind to think in terms of namespaces, here are
> examples from other languages:

What do you propose?

I think "rename everything" doesn't look like a viable option?

[...]

> Again you strawman my argument. Try to understand my central point, and
> then reply to that instead of details of "how you do it right now and that
> works for you".

This is not very constructive. Entering a culture and saying "hey, now you
do everything this way" most probably won't lead to progress, I fear.

I get your points, but now: what could be a way forward?

Cheers
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

> This was a major motivation for the `seq` and `map` packages, and maybe
> we should keep doing that with more things (e.g. add a `list` package
> where all the list functions get a new name using the `list` prefix, or
> add a `process` package were all the process related primitives are
> given a "process-"prefix, ...).


Yes, and given we can make aliases to the old names we don't break backward
compatibility, and we can reasonably easily write something that converts
existing code to the new names, and eventually deprecate the old names :-)

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 869 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> I think "rename everything" doesn't look like a viable option?
>
> > Again you strawman my argument. Try to understand my central point, and
> > then reply to that instead of details of "how you do it right now and
> that
> > works for you".
>
> This is not very constructive. Entering a culture and saying "hey, now you
> do everything this way" most probably won't lead to progress, I fear.
>
> I get your points, but now: what could be a way forward?


Well I never said "do everything this way". I was asked to clarify my
opinion so I did.

Anyway, I think like Stefan proposed a simple way would be to introduce a
"clean namespace API" where old names can be aliases to the new names (or
maybe new names are aliases to the old ones)

So, basically something like list.el containing:

(defalias 'list-append 'append)
(defalias 'list-map 'mapcar)
(defalias 'list-add 'add-to-list)

I also think having a clean API would be more newbies-friendly and thus
favor contribution from new authors, but it's just a gut feeling.

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 1544 bytes --]

Re: [ELPA] New package: transient

[Stefan Kangas]

<tomas@tuxteam.de> writes:

> > It is much easier for the mind to think in terms of namespaces, here are
> > examples from other languages:
>
> What do you propose?
>
> I think "rename everything" doesn't look like a viable option?

I'm not sure "everything" would have to be renamed.  Only the names
that do not follow the prefix convention, at least in some of the more
important cases (alist is a good example).  I think that would be a
big improvement.

We could use 'define-obsolete-function-alias' to do that.  We are
under no obligation to remove the obsolete aliases, so it would not
have to break any existing code.

Best regards,
Stefan Kangas

Re: [ELPA] New package: transient

[tomas]

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

On Wed, Apr 29, 2020 at 03:53:12PM +0200, Stefan Kangas wrote:
> <tomas@tuxteam.de> writes:
> 
> > > It is much easier for the mind to think in terms of namespaces, here are
> > > examples from other languages:
> >
> > What do you propose?
> >
> > I think "rename everything" doesn't look like a viable option?
> 
> I'm not sure "everything" would have to be renamed.  Only the names
> that do not follow the prefix convention, at least in some of the more
> important cases (alist is a good example).  I think that would be a
> big improvement.
> 
> We could use 'define-obsolete-function-alias' to do that.  We are
> under no obligation to remove the obsolete aliases, so it would not
> have to break any existing code.

That sounds plausible, yes. I think Lisp oldtimers would tend to
use the "classical" names, they are deeply ingrained. But aliasing
sounds friendly to both parties :)

Cheers
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Yuan Fu]

> On Apr 29, 2020, at 9:32 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
> FWIW, I completely agree with this.
> Emacs's own "core" library should follow the "prefix" convention.
> The resulting "structuring" of the names would help discoverability
> 
> This was a major motivation for the `seq` and `map` packages, and maybe
> we should keep doing that with more things (e.g. add a `list` package
> where all the list functions get a new name using the `list` prefix, or
> add a `process` package were all the process related primitives are
> given a "process-"prefix, ...).
> 
> 
>        Stefan
> 

It would be nice to organize all the file-related functions better. Currently all the file-xx, file-name-xx, directory-xx names are not the easiest to find. I still could find them easily despite having used them for many times. 

It would be also nice if we can add some common shortcuts like

(defun file-content (file)
  (with-temp-buffer
    (insert-file-contents file)
    (buffer-substring-no-properties)))

That should prevents people from writing 

(find-file file)
(buffer-string)


Yuan

Re: [ELPA] New package: transient

[Yuan Fu]

> I still could find them easily despite having used them for many times. 
s/could/could not

Yuan

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Wed, 29 Apr 2020 15:12:50 +0200
> Cc: Jonas Bernoulli <jonas@bernoul.li>, Emacs developers <emacs-devel@gnu.org>, 
> 	Adam Porter <adam@alphapapa.net>, Kyle Meyer <kyle@kyleam.com>, 
> 	Stefan Monnier <monnier@iro.umontreal.ca>
> 
>  > * https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes
>  assoc,
>  >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I
>  want? I
>  >  can't, I have to go to that webpage and read it all.
> 
>  I think "C-h d alist RET" is your friend.
> 
> You miss the central point of my argument.

I'm sorry to have missed that, but all I had was what you wrote:

  How am I supposed to use `C-h f alist TAB` to discover the function
  I want?

From that I assumed that I could use the fact that "alist" is part of
what you did know.  How could I have guessed this wasn't what you
meant?

> The problem is not that the doc is hard to find, it's that I *have* to
> find it to know which are the related functions.

If "alist" is not a keyword that could be used in this case, then what
is? "associaion list"? something else?  When one tries to discover
functionality, one must start with something, we cannot start with
nothing, can we?

> It is much easier for the mind to think in terms of namespaces, here are examples from other languages:
> 
> * https://clojure.github.io/clojure/clojure.string-api.html all string functions stored under string
> * http://www.cplusplus.com/reference/cstring/ almost all string manipulation function start with "str"
> * https://ruby-doc.org/stdlib-2.4.1/libdoc/fileutils/rdoc/FileUtils.html all file manipulation function are stored in
>  FileUtils::
> 
> I could go on but I think you should be able to understand my examples.

I understand the examples, I just don't think you can expect the world
to be so simple.  <cstring> in C++ has just 20 functions, and if you
need to work with multibyte strings, you won't find them there, they
are in <cwchar>, which doesn't even have "string" in its name.

Let's take a simple example: shell-command-to-string.  To which
"namespace" it should belong, in your opinion?  It is relevant to
"shell", "commands", "programs", and "strings".

And then there's the problem of having too many APIs in the same
namespace, if it indeed includes everything relevant.

> * autocompletion can help you guess the right function.
> * searching for function names (C-h f) can help you find the right function.

YMMV, but when completion shows me more than 2 dozen candidates, I'm
infinitely annoyed, and usually give up in despair much earlier that I
read the entire list.

No single trick is perfect, so my conclusion is that we need all of
them to discover what we want quickly and efficiently.  I mention
"C-h d" because people tend to forget about it.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Wed, 29 Apr 2020 15:19:56 +0200
> Cc: Jonas Bernoulli <jonas@bernoul.li>, Emacs developers <emacs-devel@gnu.org>, 
> 	Adam Porter <adam@alphapapa.net>, Kyle Meyer <kyle@kyleam.com>, 
> 	Stefan Monnier <monnier@iro.umontreal.ca>
> 
> To further illustrate my point, this doesn't lists `assq` or `assoc`, both functions being indispensable when
> using alists.

These are not special to alists, they handle any kind of list.

And getting back to the point: how would namespaces help here?  If you
were after functions that handle alists, would you find a function
called list-assoc?

And what to do with functions that work on many different types of
arguments, like 'length' and 'nth' and 'aref'? in what namespace to
put them?

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Date: Wed, 29 Apr 2020 17:28:53 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: adam@alphapapa.net, kyle@kyleam.com, jonas@bernoul.li,
>  monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> > To further illustrate my point, this doesn't lists `assq` or `assoc`, both functions being indispensable when
> > using alists.
> 
> These are not special to alists, they handle any kind of list.

Oops, sorry, I thought about memq etc.  Not enough coffee, I guess.

RE: [ELPA] New package: transient

[Drew Adams]

> if everything related to a package starts with the same namespace, so I'd be in favor of `transient-current-prefix`, `transient-current-command`, `transient-define-command`, `transient-define-prefix`, etc.

FWIW: If you're looking for a shorter prefix
then "x" as an abbreviation of "trans" is one
possibility.  No, it's not obvious to most
people, but it is a possibility.

xient-define-(command|prefix) etc.

https://english.stackexchange.com/q/200356/51214

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> >  > *
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
> sometimes
> >  assoc,
> >  >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist
> TAB` to discover the function I
> >  want? I
> >  >  can't, I have to go to that webpage and read it all.
> >
> >  I think "C-h d alist RET" is your friend.
> >
> > You miss the central point of my argument.
>
> I'm sorry to have missed that, but all I had was what you wrote:
>
>   How am I supposed to use `C-h f alist TAB` to discover the function
>   I want?
>

I think you're not noticing that in the list above "assq" and "assoc" are
not findable using "alist".


> The problem is not that the doc is hard to find, it's that I *have* to
> > find it to know which are the related functions.
>
> If "alist" is not a keyword that could be used in this case, then what
> is? "associaion list"? something else?  When one tries to discover
> functionality, one must start with something, we cannot start with
> nothing, can we?
>

No no, I *want* to use "alist" but cannot because it's not properly
namespaced.



> It is much easier for the mind to think in terms of namespaces, here are
> examples from other languages:
> >
> > * https://clojure.github.io/clojure/clojure.string-api.html all string
> functions stored under string
> > * http://www.cplusplus.com/reference/cstring/ almost all string
> manipulation function start with "str"
> > * https://ruby-doc.org/stdlib-2.4.1/libdoc/fileutils/rdoc/FileUtils.html
> all file manipulation function are stored in
> >  FileUtils::
> >
> > I could go on but I think you should be able to understand my examples.
>
> I understand the examples, I just don't think you can expect the world
> to be so simple.  <cstring> in C++ has just 20 functions, and if you
> need to work with multibyte strings, you won't find them there, they
> are in <cwchar>, which doesn't even have "string" in its name.
>

Focusing on exceptions is again avoiding the central argument.


Let's take a simple example: shell-command-to-string.  To which
> "namespace" it should belong, in your opinion?  It is relevant to
> "shell", "commands", "programs", and "strings".
>

Under the "shell-" namespace is fine, the primary goal of this api is to
run a shell command.

Anyway, to steelman your argument yes, for some fonctions it might be
complicated, especially generic ones. There are various solutions to this
but the main factor in finding them is to focus on the main argument of my
proposal: there are lots of domains where my proposal makes a lot of sense:
process-*, file-*, directory-*, buffer-*, etc. You could start by
acknowledging this. For the generic fonctions, we can either namespace them
under generic-*, or alias them for each namespace like "list-lenght",
"vector-length" etc.

We could also not touch them at all and improve the rest where everyone
agrees first, and focus on theses corner cases later.

I am sure that if other langages solved it we can too, let's not be in the
"perfect solution" bias ;-)

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 5213 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 29 Apr 2020 09:32:00 -0400
> Cc: Adam Porter <adam@alphapapa.net>, Eli Zaretskii <eliz@gnu.org>,
>  Jonas Bernoulli <jonas@bernoul.li>, Kyle Meyer <kyle@kyleam.com>,
>  Emacs developers <emacs-devel@gnu.org>
> 
> FWIW, I completely agree with this.
> Emacs's own "core" library should follow the "prefix" convention.
> The resulting "structuring" of the names would help discoverability
> 
> This was a major motivation for the `seq` and `map` packages, and maybe
> we should keep doing that with more things (e.g. add a `list` package
> where all the list functions get a new name using the `list` prefix, or
> add a `process` package were all the process related primitives are
> given a "process-"prefix, ...).

Sure, if we don't mind having much more symbols, why not?  But someone
would have to come up with such a classification, and that may not
always be easy.

Re: [ELPA] New package: transient

[Stefan Monnier]

> Sure, if we don't mind having much more symbols, why not?  But someone
> would have to come up with such a classification, and that may not
> always be easy.

Reaching the "end goal" is indeed quite hard (after all, it's
a classification job so it's both hard and impossible).

Making steps toward that goal should be pretty easy, OTOH.

The benefits will likely be small as well, sadly: it will take time and
efforts for the code to start making use of those new names, and during
many many years both names will have to exist.

The success of the `f` and `s` libraries suggests that it might be worth
the trouble, tho.

We could start with the existing "file-name-" prefix and add to it the
few functions which don't obey that prefix (e.g.  `abbrev-file-name` and
`expand-file-name`).


        Stefan

RE: [ELPA] New package: transient

[Drew Adams]

> (after all, it's a classification job so it's
>  both hard and impossible).

I love this.  A wonderful formulation.  To be cited.

Part of the impossibility being that there's no
reconciling lumpers & splitters, etc. (Not just
lumpers & splitters, of course - any differences
in classification.)

"both hard and impossible" - great point, really.
___

https://en.wikipedia.org/wiki/Lumpers_and_splitters

Re: [ELPA] New package: transient

[Robert Pluim]

>>>>> On Wed, 29 Apr 2020 15:50:52 +0200, Philippe Vaucher <philippe.vaucher@gmail.com> said:

    Philippe> (defalias 'list-append 'append)
    Philippe> (defalias 'list-map 'mapcar)
    Philippe> (defalias 'list-add 'add-to-list)

list-map is 'mapc', surely? *duck*

Robert

Re: [ELPA] New package: transient

[Alan Mackenzie]

Hello, Philippe.

On Wed, Apr 29, 2020 at 15:12:50 +0200, Philippe Vaucher wrote:

> > > *
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
> > sometimes assoc,
> > >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB`
> > to discover the function I want? I
> > >  can't, I have to go to that webpage and read it all.

> > I think "C-h d alist RET" is your friend.


> You miss the central point of my argument. The problem is not that the doc
> is hard to find, it's that I *have* to find it to know which are the
> related functions.

Let me put it to you that there is NO PROBLEM here.  If you, for any
reason, forget the function name `assq' you can find it within seconds
by typing i alist in the manual.  And if you don't like reading
documentation, why make that everybody else's problem?

> It is much easier for the mind to think in terms of namespaces, .....

Whose mind would that be?  It is much easier for me to read short words
than long words, and that applies to code as much as to text.

What are you proposing to do?  Replace `assq' with `list-assq'?  YUCK!
This will make code more turgid, and thus more difficult to read.  And
then, will we get `math-+' and `math-*', as though we were programming
in Java?  Double yuck! 

> .... here are examples from other languages:

[ .... ]

> I could go on but I think you should be able to understand my examples.

Maybe, maybe not, but I disagree with you wholeheartedly.

> Once related functions are namespaced together, almost all tooling benefit
> from it. No need to provide a manual grouping the unrelated functions
> together, just document each function:

What "tooling benefit"?  The manual groups related functions together,
not unrelated ones.  You want to fragment the manual into just
documenting each function separately?  I disagree strongly with this,
too.

What you want to do is to bloat out our source code by replacing decades
old traditional names with "namespaced" names.  Taken to extremes, you
want to replace car and cdr with list-car and list-cdr.  People hacking
on Emacs tend to be of a higher intellectual calibre than to need such
mental aids.

>    - autocompletion can help you guess the right function.
>    - searching for function names (C-h f) can help you find the right
>    function.

As can typing i in the manual.

> > > *
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html
> > > sometimes named logically (nth, remove, append), sometimes named
> > > after implementation detail (car, cdr), and no grouping at all so
> > > I can't `C-h f list TAB`

> > Also, the 'i' command in Info.

> > But you said you didn't want to read manuals, so I'm not sure why the
> > examples are from the manual.

> Again you strawman my argument. Try to understand my central point,
> and then reply to that instead of details of "how you do it right now
> and that works for you".

I understand your central point only too well.  You want to impose
bucket-loads of work, disrupting Emacs development, bloating out code,
making it more difficult to read and understand.  And all for what?  So
that the very occasional trip to a manual by a newcomer can be spared?

Tell me, how would you feel if somebody decided to "namespace" your
name, Philippe Vaucher?  I would guess that you would decide you like
your name the way it is.

> Kind regards,
> Philippe

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [ELPA] New package: transient

[Clément Pit-Claudel]

On 29/04/2020 09.50, Philippe Vaucher wrote:
>     I think "rename everything" doesn't look like a viable option?
> 
>     > Again you strawman my argument. Try to understand my central point, and
>     > then reply to that instead of details of "how you do it right now and that
>     > works for you".
> 
>     This is not very constructive. Entering a culture and saying "hey, now you
>     do everything this way" most probably won't lead to progress, I fear.
> 
>     I get your points, but now: what could be a way forward?
> 
> 
> Well I never said "do everything this way". I was asked to clarify my opinion so I did.
> 
> Anyway, I think like Stefan proposed a simple way would be to introduce a "clean namespace API" where old names can be aliases to the new names (or maybe new names are aliases to the old ones)
> 
> So, basically something like list.el containing:
> 
> (defalias 'list-append 'append)
> (defalias 'list-map 'mapcar)
> (defalias 'list-add 'add-to-list)

We have seq-append and seq-map for the first two; do we need the list- versions too?

Re: [ELPA] New package: transient

[tomas]

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

On Wed, Apr 29, 2020 at 05:27:39PM +0000, Alan Mackenzie wrote:

[...]

> Whose mind would that be?  It is much easier for me to read short words
> than long words, and that applies to code as much as to text.
> 
> What are you proposing to do?  Replace `assq' with `list-assq'?  YUCK!
> This will make code more turgid, and thus more difficult to read.

That's it. Reading ease is, after all, in the eye of the beholder.
That's what I was trying to convey. I definitely prefer "car" and
"cdr" to "first" and "butfirst" [1] -- *because that's what I am
used to*
 
>                                                                    And
> then, will we get `math-+' and `math-*', as though we were programming
> in Java?  Double yuck! 

[...]

That's why I tried to frame this as a question of culture.
Languages in general (programming languages in particular) are a
means of communication between people. Changing a program to accept
different symbols is easy (well...) -- but changing an existing
culture with people in it is way harder; it will take some convincing
powers. That's what I was trying to get across.

Cheers

[1] with a tip o' the hat to LOGO
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > So, basically something like list.el containing:
> >
> > (defalias 'list-append 'append)
> > (defalias 'list-map 'mapcar)
> > (defalias 'list-add 'add-to-list)
>
> We have seq-append and seq-map for the first two; do we need the list-
> versions too?
>

No of course we don't. It might make more sense to enhance seq to cover all
list/vector operations.

[-- Attachment #2: Type: text/html, Size: 632 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
>     Philippe> (defalias 'list-append 'append)
>     Philippe> (defalias 'list-map 'mapcar)
>     Philippe> (defalias 'list-add 'add-to-list)
>
> list-map is 'mapc', surely? *duck*
>

Please don't take this example literaly, it is just an example ;-)

[-- Attachment #2: Type: text/html, Size: 528 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > You miss the central point of my argument. The problem is not that the
> doc
> > is hard to find, it's that I *have* to find it to know which are the
> > related functions.
>
> Let me put it to you that there is NO PROBLEM here.  If you, for any
> reason, forget the function name `assq' you can find it within seconds
> by typing i alist in the manual.  And if you don't like reading
> documentation, why make that everybody else's problem?
>

I suggest you go out an take a deep breathe. Your tone is extremely
unpleasant, and remember that I was asked to clarify what I meant so I did.

At no point am I suggesting this is mandatory and that everyone should do
like I say.

(it also looks like you still don't really understand my point based on the
example you cite)


> > It is much easier for the mind to think in terms of namespaces, .....
>
> Whose mind would that be?  It is much easier for me to read short words
> than long words, and that applies to code as much as to text.
>
> What are you proposing to do?  Replace `assq' with `list-assq'?  YUCK!
> This will make code more turgid, and thus more difficult to read.  And
> then, will we get `math-+' and `math-*', as though we were programming
> in Java?  Double yuck!
>

I never talk about replacements.



> > Once related functions are namespaced together, almost all tooling
> benefit
> > from it. No need to provide a manual grouping the unrelated functions
> > together, just document each function:
>
> What "tooling benefit"?  The manual groups related functions together,
> not unrelated ones.  You want to fragment the manual into just
> documenting each function separately?  I disagree strongly with this,
> too.
>

I never talked about fragmenting the manual.



> What you want to do is to bloat out our source code by replacing decades
> old traditional names with "namespaced" names.  Taken to extremes, you
> want to replace car and cdr with list-car and list-cdr.  People hacking
> on Emacs tend to be of a higher intellectual calibre than to need such
> mental aids.
>

Wow.



> > Again you strawman my argument. Try to understand my central point,
> > and then reply to that instead of details of "how you do it right now
> > and that works for you".
>
> I understand your central point only too well.  You want to impose
> bucket-loads of work, disrupting Emacs development, bloating out code,
> making it more difficult to read and understand.  And all for what?  So
> that the very occasional trip to a manual by a newcomer can be spared?
>
> Tell me, how would you feel if somebody decided to "namespace" your
> name, Philippe Vaucher?  I would guess that you would decide you like
> your name the way it is.


Wow. Yeah I want to impose bucket-loads of work, I want to disrupt Emacs
development. That's totally not strawmaning my position. Not at all.

I understand I apparently touched a nexus by discussing this and having
some people agree with me, but if you are not able to discuss this in an
open manner I suggest you refrain from discussing it at all.

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 4345 bytes --]

Re: [ELPA] New package: transient

[Clément Pit-Claudel]

On 29/04/2020 13.27, Alan Mackenzie wrote:
> I understand your central point only too well.  You want to impose 
> bucket-loads of work, disrupting Emacs development, bloating out 
> code, making it more difficult to read and understand. [...] Tell
> me, how would you feel if somebody decided to "namespace" your name,
> Philippe Vaucher?

Surely the question of adding a separate namespace of alist functions can be debated without such vitriol.

Re: [ELPA] New package: transient

[Stefan Monnier]

Hi Alan,

> I understand your central point only too well.  You want to impose
> bucket-loads of work, disrupting Emacs development, bloating out code,
> making it more difficult to read and understand.  And all for what?  So
> that the very occasional trip to a manual by a newcomer can be spared?

Wait.. is that snow I see outside?


        Stefan

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It would be nice to organize all the file-related functions
  > better. Currently all the file-xx, file-name-xx, directory-xx
  > names are not the easiest to find.

What is the difficulty?  Doesn't M-x apropos RET ^file RET do it?

There may be some important context I can't get from your message.

  > (defun file-content (file)
  >   (with-temp-buffer
  >     (insert-file-contents file)
  >     (buffer-substring-no-properties)))

I think he name should be file-contents, plural.  The text in the file
is its "contents".

If people often want this, we can certainly add it.
It is just a question of how often programmers want it.


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I think "C-h d alist RET" is your friend.
  > >

  > To further illustrate my point, this doesn't lists `assq` or `assoc`, both
  > functions being indispensable when using alists.

We can fix that easily enough.  We just have to add some use of the
pertinent keywords to the doc strings of functions that need such
help.  For instance, make sure that "alist" appears in the doc strings
of 'assq' and 'assoc'.

The hardest part would be noticing which functions could use this help.

The massive renamings that some have proposed would not only be
drastic and atrocious.  They would also be a lot more work than this
easy solution.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The TL;DR is:

  > > Taking inspiration from prefix keys and prefix arguments, Transient
  > > implements a similar abstraction involving a prefix command, infix
  > > arguments and suffix commands. [...] When the user calls a transient
  > > prefix command, then a transient (temporary) keymap is activated,
  > > which binds the transient's infix and suffix commands, [...] The
  > > available suffix and infix commands and their state are shown in a
  > > popup buffer until the transient is exited by invoking a suffix
  > > command.

That focuses on _how_ it works, but could you tell us in concrete
terms what job it does?  Perhaps show us an example of use.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > For people with some roots in Lisp culture (I'm one of them,
  > mind you), "alist" is obvious. It's an association list, duh.
  > For newcomers... not so much.

Here's how the Emacs Lisp Reference Manual tells Lisp programmers
about this.

    5.8 Association Lists
    =====================

    An “association list”, or “alist” for short, records a mapping from keys
    to values.  It is a list of cons cells called “associations”: the CAR of
    each cons cell is the “key”, and the CDR is the “associated value”.(1)

Is there a way to make this better?
Where else could we do better?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The names assoc, assq, rassoc and rassq come from old Lisp tradition.
Maclisp used them in the 1970s.  I would guess they go back to 1960.
If I had changed them in 1984 when writing Emacs Lisp, I would have
been throwing away my tradition and making Emacs strange to Lisp
hackers.

     > named logically (nth, remove, append), sometimes named after implementation

Those are also part of old Lisp tradition.

     > detail (car, cdr),

Those two functions are among the first Lisp functions ever defined
and named, in 1958 I think.  Along with 'cons' and 'eq'.

Lisp has a deep history and culture, and replacing the traditional names
names would be as intolerable as reforming English to phonetic
spelling.


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Phil Sainty]

On 30/04/20 2:29 pm, Richard Stallman wrote:
> That focuses on _how_ it works, but could you tell us in concrete
> terms what job it does?  Perhaps show us an example of use.

I had a look for videos showing the usage of this package within
Magit and, if you're able to download YouTube videos, then I think
this one will help:

https://youtu.be/NDP91RNgT4A?t=180

Starting from minute 3:00 you will regularly see Transient buffers in
use, popping up at the bottom of the frame, showing menus of commands
and the key sequences which invoke them.  Some keys will change the
state of the Transient buffer by toggling or setting options (possibly
involving minibuffer usage to input arguments); other keys will close
the Transient buffer and initiate some action command (utilising the
options which were selected).  In Magit the options are shown at the
top and the actions at the bottom of the buffer.

In brief a 'prefix' key binding will open a particular Transient menu
to allow you to select from the set of commands under that 'prefix',
possibly configuring some options along the way to modify how the
final selection will behave.  It's a very nice approach in practice --
both efficient and informative.

In the case of Magit it helps to make some quite complicated or
obscure tasks remarkably simple to perform, by presenting all the
things you might need for a particular class of activity in one
easy-to-comprehend, nicely presented, keyboard-driven menu.

The itself video is a bit of a whirlwind tour of some Magit features
rather than a focus on Transient specifically, so it doesn't go into
any depth on how those menus work; but on the other hand it's pretty
short, and with the speed it goes at you will see several different
Transient buffers along the way, so hopefully you'll get a bit of a
feel for it.


-Phil

Re: [ELPA] New package: transient

[Zhu Zihao]

I think seq.el and map.el is a much more modern replacement for classical Lisp
list(alist/plist) manipulation API :)

Re: [ELPA] New package: transient

[Alan Mackenzie]

Hello, Philippe.

On Wed, Apr 29, 2020 at 21:31:46 +0200, Philippe Vaucher wrote:

> > > You miss the central point of my argument. The problem is not that the
> > > doc is hard to find, it's that I *have* to find it to know which
> > > are the related functions.

> > Let me put it to you that there is NO PROBLEM here.  If you, for any
> > reason, forget the function name `assq' you can find it within seconds
> > by typing i alist in the manual.  And if you don't like reading
> > documentation, why make that everybody else's problem?


> I suggest you go out an take a deep breathe. Your tone is extremely
> unpleasant, and remember that I was asked to clarify what I meant so I did.

Thanks for reacting to my post.

> At no point am I suggesting this is mandatory and that everyone should do
> like I say.

[ .... ]

> I never talk about replacements.

In another post on this thread, you wrote:

> Yes, and given we can make aliases to the old names we don't break
> backward compatibility, and we can reasonably easily write something
> that converts existing code to the new names, and eventually deprecate
> the old names :-)

That looks strongly to me about replacements.  And note you used the verb
form "can" rather than the more gentle, conditional form "could".

I don't see anything but a desired compulsion implied by that paragraph.

There has not yet been a discussion about whether your proposed change is
a good idea or not.  I am suggesting, strongly, it is not.

[ .... ]

> I understand I apparently touched a nexus by discussing this and having
> some people agree with me, but if you are not able to discuss this in an
> open manner I suggest you refrain from discussing it at all.


> Kind regards,
> Philippe

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [ELPA] New package: transient

[tomas]

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

(snipped CC list -- I think most are on -devel anyway)

On Thu, Apr 30, 2020 at 11:51:08AM +0000, Alan Mackenzie wrote:

[...]

> > Yes, and given we can make aliases to the old names we don't break
> > backward compatibility, and we can reasonably easily write something
> > that converts existing code to the new names, and eventually deprecate
> > the old names :-)
> 
> That looks strongly to me about replacements.  And note you used the verb
> form "can" rather than the more gentle, conditional form "could".

That's it. Although my feeling is that your (Alan) reaction was too
sharp, I also feel that you, Philippe, disregard the cultural aspects
of your proposal -- your approach "hey, let's deprecate this-and-that"
is bound to ruffle some feathers and even hurt some people.

And when people react ("hell, no!"), you're offended and drive deeper
in your denial of the "other side's" points.

I've observed this situation unfold far too often in free software:
at least it hinders progress, and at worst it destroys friendships.

Don't let us get there.

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Arthur Miller]

tomas@tuxteam.de writes:

> On Wed, Apr 29, 2020 at 01:33:08PM +0300, Eli Zaretskii wrote:
>> > Date: Wed, 29 Apr 2020 12:17:55 +0200
>> > From: <tomas@tuxteam.de>
>> > 
>> > > > * https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes assoc,
>> > > >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I want? I
>> > > >  can't, I have to go to that webpage and read it all.
>> > > 
>> > > I think "C-h d alist RET" is your friend.
>> > 
>> > Yes, but :)
>> > 
>> > For people with some roots in Lisp culture (I'm one of them,
>> > mind you), "alist" is obvious. It's an association list, duh.
>> > For newcomers... not so much.
>> 
>> I was replying to the above, where the issue is that not all of the
>> functions' names begin with "alist".  Evidently, this means the
>> "alist" obstacle was already overcome.
>
> In the concrete, yes. I still mull over the more general
> problem (without having a good idea, unfortunately).
>
> I just wanted to raise some awareness, since it's an
> ever-recurring pattern.
>
> Cheers
> -- t
I think you are completely right. API naming in Emacs could use some
more love. "Namespacing" probably can't be used for
everything, but it would be useful if stuff was prefixed by api
where possible. I would also find it usefull if names reflected
more of functionality where it can. I use helm and try to discover
API from the list of compeletions, but it does not work so well when
names are not really reflecting important differences. For example
make-process and call-process - which one was asynchronous? I have to
look it up in either comments in source or manual, because there is
nothing in the name that suggests which one to use.

Of course namespacing *everythign* is probably not possible, but
where possible I think namespacing and maybe more carefull choosen
names would help. It certainly can't make things worse.
I don't understand why so much resistence to your remark in rest of
answers.

Re: [ELPA] New package: transient

[tomas]

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

On Thu, Apr 30, 2020 at 02:44:47PM +0200, Arthur Miller wrote:
> tomas@tuxteam.de writes:

[...]

> > I just wanted to raise some awareness, since it's an
> > ever-recurring pattern.
> >
> > Cheers
> > -- t
> I think you are completely right. API naming in Emacs could use some
> more love. "Namespacing" probably can't be used for
> everything, but it would be useful if stuff was prefixed by api
> where possible [...]

If you are replying to my post -- I took care to not take a position
on the thing itself: there are already positions which are strong
enough. I was arguing for both sides to take care of each other :)

Where am I? I'd leave traditional Lisp names where they are. When
inventing new names, by all means try to make them regular (which,
as we know, is hard /and/ impossible, but trying already helps).

Cheers
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 30.04.2020 15:38, tomas@tuxteam.de wrote:
> And when people react ("hell, no!"), you're offended and drive deeper
> in your denial of the "other side's" points.

When offended people overreact and make up strawmen, that's when the 
discussion is derailed.

It's very hard to move forward (at all) if nobody creates proposals on 
"how we should be doing things better", or if they are actively shunned. 
And it's on us, as a community, to be able to discuss them 
constructively, on the merits.

FWIW, my position is we don't need to change everything, especially not 
the low-level functions (car and aref are fine; seq.el and map.el 
provide good generic replacements), but the problem is real. And "you 
can use the index in the manual" is not a good replacement for 
consistent naming conventions.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> FWIW, my position is we don't need to change everything, especially not
> the low-level functions (car and aref are fine; seq.el and map.el
> provide good generic replacements), but the problem is real. And "you
> can use the index in the manual" is not a good replacement for
> consistent naming conventions.
>

Finally someone who sees the moon instead of arguing about the finger.

[-- Attachment #2: Type: text/html, Size: 622 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 29.04.2020 18:25, Philippe Vaucher wrote:
> For the generic fonctions, we can either namespace them under generic-*, 
> or alias them for each namespace like "list-lenght", "vector-length" etc.

In this particular example, though, seq-length should be enough. Or just 
'length'.

Speaking of alists, though, 'alist-get' is discoverable enough, and also 
powerful (you can use it instead of both assoc and assq).

'copy-alist' is not so discoverable using the default completion 
settings. It *is* discoverable with fido-mode, though. Or with 
ido-ubiquitous (3rd party package).

Hopefully we'll drift toward more fuzzy completion over time in the 
default configuration too.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > > Yes, and given we can make aliases to the old names we don't break
> > > backward compatibility, and we can reasonably easily write something
> > > that converts existing code to the new names, and eventually deprecate
> > > the old names :-)
> >
> > That looks strongly to me about replacements.  And note you used the verb
> > form "can" rather than the more gentle, conditional form "could".
>
> That's it. Although my feeling is that your (Alan) reaction was too
> sharp, I also feel that you, Philippe, disregard the cultural aspects
> of your proposal -- your approach "hey, let's deprecate this-and-that"
> is bound to ruffle some feathers and even hurt some people.
>

I'm amazed that you reach this conclusion based on this story. My main
argument was "hey, let's add a clearer api where it makes sense, so things
are better namespaced".

People kept nitpicking about the alist example not being good enough, so I
raise other examples where it's more obvious (file*, buffer*, process*,
window*) but people keep on going back to the alist example, as if it's
impossible for you to steelman my argument.

Anyway Stefan agreed and proposed something about list. I said good idea
and we can make alias to the old names (that means KEEP the old names), and
EVENTUALLY (in a far future) deprecate the old names, and what you guys
deduce from this? That I want to rename the existing API right now.

This is strawmaning my position, I believe you wanted me to have this
position because you felt threatened by change.



> And when people react ("hell, no!"), you're offended and drive deeper
> in your denial of the "other side's" points.
>

It looks like you never consider that I'm not denying the other side's
point, I'm saying they are not relevant to my argument.

IMHO valid rebuttals to my argument would have been:

- It's too much work.
- The supposed advantages are not demonstrated.
- It will create two APIs to maintain (even tho they would only be aliases
but still a valid argument).

But certainly not:

- look, some parts of the string library in C does not follow this so your
idea is not valid
- emacs lisp is not namespaced because that is how we filter smarter people
- if we start namespaceing one api then we will end up with math.+ because
it's impossible to apply your idea in a sane way

Of course I also strawman your arguments here, but you'd get my point.
Address the center of the target, not its periphery.

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 3337 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

> On 29.04.2020 18:25, Philippe Vaucher wrote:
> > For the generic fonctions, we can either namespace them under generic-*,
> > or alias them for each namespace like "list-lenght", "vector-length" etc.
>
> In this particular example, though, seq-length should be enough. Or just
> 'length'.
>

Yes. As proposed we'd think about which topic would benefit the most from
being properly namespaced. Controversial topics should remain untouched
until some consensus is reached.

https://github.com/magnars/s.el and https://github.com/rejeep/f.el are good
starting points, but as others mentionned process-* is probably a good
candidate as well.

Philippe

[-- Attachment #2: Type: text/html, Size: 1090 bytes --]

Re: [ELPA] New package: transient

[tomas]

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

On Thu, Apr 30, 2020 at 08:30:43PM +0300, Dmitry Gutov wrote:
> On 30.04.2020 15:38, tomas@tuxteam.de wrote:
> >And when people react ("hell, no!"), you're offended and drive deeper
> >in your denial of the "other side's" points.
> 
> When offended people overreact and make up strawmen, that's when the
> discussion is derailed.
> 
> It's very hard to move forward (at all) if nobody creates proposals
> on "how we should be doing things better", or if they are actively
> shunned. And it's on us, as a community, to be able to discuss them
> constructively, on the merits.

It's "on us" as it is "on everyone", I think :-)

> FWIW, my position is we don't need to change everything, especially
> not the low-level functions (car and aref are fine; seq.el and
> map.el provide good generic replacements), but the problem is real.
> And "you can use the index in the manual" is not a good replacement
> for consistent naming conventions.

I think there is general agreement on that around here.

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 30.04.2020 21:19, Philippe Vaucher wrote:
> https://github.com/magnars/s.el and https://github.com/rejeep/f.el are 
> good starting points, but as others mentionned process-* is probably a 
> good candidate as well.

We should probably discuss specific proposals.

I haven't used dash/s/f much, but from what I see they do try to bring a 
more "flat" style of APIs, following the style of Clojure. There are a 
lot of utility functions in there too (like extra abstractions on top of 
the basics that the authors found to be useful). So when you ask the 
core library to be more like f.el, you'll have to specify what exactly 
you'd like to see changed: rename existing functions dealing with files 
to start with file-* or to add new ones. Then we can work out some sort 
of policy to adopt (or not) such changes.

Also, quite a bit of functions seem to be named with the purpose of 
keeping the names short, perhaps too short, like the author came over 
from Clojure, found out that you can't simply

   (require '[string-utils :as s])

so "properly namespaced" names will tend to be rather long, and decided 
to abbreviate them as much as possible. Examples: f-base, f-relative, 
f-ext. I'm not sure this will fly here.

Re: [ELPA] New package: transient

[tomas]

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

On Thu, Apr 30, 2020 at 07:53:22PM +0200, Philippe Vaucher wrote:
> >
> > FWIW, my position is we don't need to change everything [...]

> Finally someone who sees the moon instead of arguing about the finger.

To stretch the analogy a bit, if you poke your finger into
someone's eye, (s)he perhaps won't be able to see the moon.

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[tomas]

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

On Thu, Apr 30, 2020 at 08:14:28PM +0200, Philippe Vaucher wrote:

[tomas]
> > That's it. Although my feeling is that your (Alan) reaction was too
> > sharp, I also feel that you, Philippe, disregard the cultural aspects
> > of your proposal [...]

> I'm amazed that you reach this conclusion based on this story. My main
> argument was "hey, let's add a clearer api where it makes sense, so things
> are better namespaced".

I'm sorry that you are amazed. It seems I'm unable to bring across my
point.

> People kept nitpicking about the alist example not being good enough, so I
> raise other examples where it's more obvious (file*, buffer*, process*,
> window*) but people keep on going back to the alist example, as if it's
> impossible for you to steelman my argument.

No, not "not good enough". People around here /care/ about the alist
examples, since it's core Lisp terminology. It may be a bit strange,
but it makes programs more readable to people around here. Changing
that is not only a technical question, and if you don't account for
that, strong reactions are to be expected.

This is the point I think you may be missing.

> Anyway Stefan agreed and proposed something about list. I said good idea
> and we can make alias to the old names (that means KEEP the old names), and
> EVENTUALLY (in a far future) deprecate the old names, and what you guys
> deduce from this? That I want to rename the existing API right now.

Right now, eventually -- some care strongly about keeping parts of it.
It's, of course, on them to listen to you -- but it's on you to accept
their position, too.

> This is strawmaning my position, I believe you wanted me to have this
> position because you felt threatened by change.

This old saw. "You're just hostile to change". Please don't. I know
that from other discussions of this kind (believe me, I've witnessed
quite a few) and it is... not constructive.

> > And when people react ("hell, no!"), you're offended and drive deeper
> > in your denial of the "other side's" points.
> >
> 
> It looks like you never consider that I'm not denying the other side's
> point, I'm saying they are not relevant to my argument.

See above.

> IMHO valid rebuttals to my argument would have been:
> 
> - It's too much work.
> - The supposed advantages are not demonstrated.
> - It will create two APIs to maintain (even tho they would only be aliases
> but still a valid argument).
> 
> But certainly not:
> 
> - look, some parts of the string library in C does not follow this so your
> idea is not valid
> - emacs lisp is not namespaced because that is how we filter smarter people
> - if we start namespaceing one api then we will end up with math.+ because
> it's impossible to apply your idea in a sane way

So it's you who fixes what a "valid rebuttal" is? That's not the way
how negotiations work.

> Of course I also strawman your arguments here, but you'd get my point.
> Address the center of the target, not its periphery.

As defined by whom?

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > > That's it. Although my feeling is that your (Alan) reaction was too
> > > sharp, I also feel that you, Philippe, disregard the cultural aspects
> > > of your proposal [...]
>
> > I'm amazed that you reach this conclusion based on this story. My main
> > argument was "hey, let's add a clearer api where it makes sense, so
> things
> > are better namespaced".
>
> I'm sorry that you are amazed. It seems I'm unable to bring across my
> point.
>

Ah, I get it now. You just want to make me understand how people perceive
what I say. I agree, it's sad that I appear that way.



> > People kept nitpicking about the alist example not being good enough, so
> I
> > raise other examples where it's more obvious (file*, buffer*, process*,
> > window*) but people keep on going back to the alist example, as if it's
> > impossible for you to steelman my argument.
>
> No, not "not good enough". People around here /care/ about the alist
> examples, since it's core Lisp terminology. It may be a bit strange,
> but it makes programs more readable to people around here. Changing
> that is not only a technical question, and if you don't account for
> that, strong reactions are to be expected.
>
> This is the point I think you may be missing.
>

So you're saying the alist example is so core to Lisp terminology that we
can't infer what I'm getting at (because Lisp *is* alist named that way
etc) ? Interesting, I didn't consider that indeed.



> > Anyway Stefan agreed and proposed something about list. I said good idea
> > and we can make alias to the old names (that means KEEP the old names),
> and
> > EVENTUALLY (in a far future) deprecate the old names, and what you guys
> > deduce from this? That I want to rename the existing API right now.
>
> Right now, eventually -- some care strongly about keeping parts of it.
> It's, of course, on them to listen to you -- but it's on you to accept
> their position, too.
>

True. I guess it's because I only see reactance on their part without even
considering the idea, and I think I'm able to see where they are talking
from so I find it unfair that they don't do the same with my argument. But
that's probably a biased view.



> > This is strawmaning my position, I believe you wanted me to have this
> > position because you felt threatened by change.
>
> This old saw. "You're just hostile to change". Please don't. I know
> that from other discussions of this kind (believe me, I've witnessed
> quite a few) and it is... not constructive.
>

Yes, you're right sorry I was steaming. The fact that Alan Mackenzie never
apologized for his ugly behavior left me with a taste of revenge, I'd fix
that.


> IMHO valid rebuttals to my argument would have been:
> >
> > - It's too much work.
> > - The supposed advantages are not demonstrated.
> > - It will create two APIs to maintain (even tho they would only be
> aliases
> > but still a valid argument).
> >
> > But certainly not:
> >
> > - look, some parts of the string library in C does not follow this so
> your
> > idea is not valid
> > - emacs lisp is not namespaced because that is how we filter smarter
> people
> > - if we start namespaceing one api then we will end up with math.+
> because
> > it's impossible to apply your idea in a sane way
>
> So it's you who fixes what a "valid rebuttal" is? That's not the way
> how negotiations work.
>

I'd have worded better. By "valid" I meant "here's a non-exhaustive list of
arguments that appear to reply to the central argument". If you look at my
replies I think I always replied to these non-central arguments, but maybe
I focused too much on pointing out they were not central and people missed
my answer.



> > Of course I also strawman your arguments here, but you'd get my point.
> > Address the center of the target, not its periphery.
>
> As defined by whom?


Good point, what is central and not is subjective. I guess my belief in
trying to steelman the other's position resulted in me calling out those
who didn't my position. I'd correct that.

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 5657 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

> I haven't used dash/s/f much, but from what I see they do try to bring a
> more "flat" style of APIs, following the style of Clojure. There are a
> lot of utility functions in there too (like extra abstractions on top of
> the basics that the authors found to be useful). So when you ask the
> core library to be more like f.el, you'll have to specify what exactly
> you'd like to see changed: rename existing functions dealing with files
> to start with file-* or to add new ones. Then we can work out some sort
> of policy to adopt (or not) such changes.
>

I think the crux of the issue regarding existing Emacs lisp would be
"should all file related apis start with file- ?"

If we decide the answer is yes (as advised by the coding conventions) we
could start by simply aliasing the existing API that does not follow this
convention. That'd mean `copy-alist` would be aliased as `alist-copy`, do
you think people would be strongly against this?


> Also, quite a bit of functions seem to be named with the purpose of
> keeping the names short, perhaps too short, like the author came over
> from Clojure, found out that you can't simply
>
>    (require '[string-utils :as s])
>

Yes, I think "string-" is better than "s-", but I understand the author
didn't want to clash with the existing "string-" functions so he picked
"s-".

In this case I think a simple proposal would be to list all the "s-"
functions that don't have a corresponding "string-" function (s-truncate,
s-left, s-right, etc) and propose them for inclusion but named under the
"string-" namespace.

Regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 2253 bytes --]

Re: [ELPA] New package: transient

[Stefan Monnier]

> I haven't used dash/s/f much, but from what I see they do try to bring
> a more "flat" style of APIs, following the style of Clojure. There are a 
> lot of utility functions in there too (like extra abstractions on top of the
> basics that the authors found to be useful). So when you ask the core
> library to be more like f.el, you'll have to specify what exactly you'd like
> to see changed: rename existing functions dealing with files to start with
> file-* or to add new ones. Then we can work out some sort of policy to adopt
> (or not) such changes.

I think we should separate the renaming proposals from the addition proposals.


        Stefan

Re: [ELPA] New package: transient

[tomas]

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

On Thu, Apr 30, 2020 at 09:13:58PM +0200, Philippe Vaucher wrote:

[...]

> > I'm sorry that you are amazed. It seems I'm unable to bring across my
> > point.

> Ah, I get it now. You just want to make me understand how people perceive
> what I say. I agree, it's sad that I appear that way.

Yes, that's it :-)

Thanks for your patience.

> So you're saying the alist example is so core to Lisp terminology that we
> can't infer what I'm getting at (because Lisp *is* alist named that way
> etc) ? Interesting, I didn't consider that indeed.

I didn't see it that way, but yes, you're right.

> > > Anyway Stefan agreed and proposed something about list. I said good idea
> > > and we can make alias to the old names (that means KEEP the old names),
> > and
> > > EVENTUALLY (in a far future) deprecate the old names, and what you guys
> > > deduce from this? That I want to rename the existing API right now.
> >
> > Right now, eventually -- some care strongly about keeping parts of it.
> > It's, of course, on them to listen to you -- but it's on you to accept
> > their position, too.
> >
> 
> True. I guess it's because I only see reactance on their part without even
> considering the idea, and I think I'm able to see where they are talking
> from so I find it unfair that they don't do the same with my argument. But
> that's probably a biased view.

All our views are biased, that's the exciting part of it :-D

> > > This is strawmaning my position, I believe you wanted me to have this
> > > position because you felt threatened by change.
> >
> > This old saw. "You're just hostile to change". Please don't. I know
> > that from other discussions of this kind (believe me, I've witnessed
> > quite a few) and it is... not constructive.
> >
> 
> Yes, you're right sorry I was steaming. The fact that Alan Mackenzie never
> apologized for his ugly behavior left me with a taste of revenge, I'd fix
> that.

Yes. I perceived his reaction as (possibly unnecessarily) sharp, and I
said so.

> > IMHO valid rebuttals to my argument would have been:

[on "valid rebuttals"]

> I'd have worded better. By "valid" I meant "here's a non-exhaustive list of
> arguments that appear to reply to the central argument". If you look at my
> replies I think I always replied to these non-central arguments, but maybe
> I focused too much on pointing out they were not central and people missed
> my answer.

I see.

> > > Of course I also strawman your arguments here, but you'd get my point.
> > > Address the center of the target, not its periphery.
> >
> > As defined by whom?
> 
> 
> Good point, what is central and not is subjective. I guess my belief in
> trying to steelman the other's position resulted in me calling out those
> who didn't my position. I'd correct that.

Hey, thanks a lot.

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> I haven't used dash/s/f much, but from what I see they do try to bring a
>> more "flat" style of APIs, following the style of Clojure. There are a
>> lot of utility functions in there too (like extra abstractions on top of
>> the basics that the authors found to be useful). So when you ask the
>> core library to be more like f.el, you'll have to specify what exactly
>> you'd like to see changed: rename existing functions dealing with files
>> to start with file-* or to add new ones. Then we can work out some sort
>> of policy to adopt (or not) such changes.
>>
>
> I think the crux of the issue regarding existing Emacs lisp would be
> "should all file related apis start with file- ?"
>
> If we decide the answer is yes (as advised by the coding conventions) we
> could start by simply aliasing the existing API that does not follow this
> convention. That'd mean `copy-alist` would be aliased as `alist-copy`, do
> you think people would be strongly against this?
>

I think I was not clear enough:

- I propose to alias (not rename) existing functions dealing with files to
start with file-
- I propose to extend this to most emacs topics (except maybe the "touchy"
ones)
- I propose to extend some of these topics with functions that looks like
good additions

For example s.el contains a lot of IMHO obvious functions that emacs could
include easily under a proper namespace that would probably not offend
anyone.

Philippe

>

[-- Attachment #2: Type: text/html, Size: 2161 bytes --]

Re: [ELPA] New package: transient

[Alan Mackenzie]

Hello, Philippe.

On Thu, Apr 30, 2020 at 21:13:58 +0200, Philippe Vaucher wrote:

[ .... ]

> Yes, you're right sorry I was steaming. The fact that Alan Mackenzie
> never apologized for his ugly behavior left me with a taste of revenge,
> I'd fix that.

First of all, let's note that your English is so good that you're either
a native speaker of it (as I am), or might as well be.

You know full well the difference between saying "we CAN make aliases to
the old names" and "we COULD make aliases to the old names".  You wrote
the first, thus suggesting you were about to stomp ahead and do it.

You also understand full well the difference between "never apologized"
and "hasn't apologized".  So you reject any apology from me in advance,
because you didn't get it within your own rather tight time scale.  I'll
apologise anyway.

My post, the objectionable one, opened up a debate which had to take
place, and might well not have done so without it.  You weren't the only
person who was "steaming".  What I saw was a relative newcomer to the
group (sorry, I still don't know your past and present) proposing to turn
Emacs Lisp upside down for some uncertain benefit on an uncertain
timescale, and not about to wait on any objections.

My thanking you this morning for your response was quite sincere.  You
could quite easily have just ignored my post.

Nevertheless, I apologise for that post (not for my "behavior"), both to
you and to the group, in that it was too personal and too aggressive, and
imputed motives to yourself which were unjustified.

[ .... ]

> Kind regards,
> Philippe

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 30.04.2020 22:26, Philippe Vaucher wrote:
> That'd mean `copy-alist` would be aliased as `alist-copy`, do you think 
> people would be strongly against this?

I don't know. I've never had an occasion to use this function. All I can 
say is that with fido-mode on (or with any of the packages like Ivy or 
Helm that provide fuzzy matching) its discoverability is not much of a 
problem.

In general, we have a generous amount of <verb>-<main thing>-etc 
function names, probably in the name of better sounding English. 
Renaming them all might be a difficult discussion. Or not, I'm not sure. 
If you want, you should probably open an improvement request just for 
this issue separately.

Re: [ELPA] New package: transient

[chad]

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

On Thu, Apr 30, 2020 at 1:55 PM Alan Mackenzie <acm@muc.de> wrote:

>  What I saw was a relative newcomer to the
> group (sorry, I still don't know your past and present) proposing to turn
> Emacs Lisp upside down for some uncertain benefit on an uncertain
> timescale, and not about to wait on any objections.
>

You seem to have missed the part of the conversation where he was
explicitly asked to make up an example of the sort of thing that he
proposed would be helpful:

On Wed, Apr 29, 2020 at 2:51 AM Philippe Vaucher <philippe.vaucher@gmail.com>
wrote:

> > Overall I think it's a shame that the Emacs api wasn't designed with
>> discoverability/consistency in mind
>>
>> Would you mind elaborate on this deficiency?  I don't think I quite
>> understand the complaint.
>
>
> It's hard to really criticize because Emacs was designed ages ago.
>
> My point is simply this one: when I look at
> https://github.com/magnars/dash.el,
> https://github.com/NicolasPetton/seq.el or https://github.com/magnars/s.el I
> can immediately understand how the library works and how to achieve things.
> I can also easily use `C-h f` to find about the function I want.
>
> In Emacs, parts of it are designed following the same principle, but a lot
> of it isn't: ...
>

Addressing the point, part one:
Computer languages (so far) are human languages; almost every example of
such we've ever seen uses both regular and irregular rules (Esperanto
exists in large part to be the exception that proves the rule). For
example, in English, the vast majority of verbs are "regular verbs", and
the conjugation thereof (cases, tenses, declensions, etc.) strictly follow
a very orderly pattern, such as "jump". This makes them esy to learn,
understand, and generate. There are also a small core of "irregular verbs",
usually the most common/basic/important concepts in the language, that do
not follow these patterns, and use bespoke differences for many of the
conjugations. These verbs must simply be rote-learned, but their use is
typically so central to communication that people memo(r)ize them
relatively quickly. In English (and many other modern languages), common
examples are "be", "do", and "have".

Emacs Lisp, being a human language, is likely to have these same
properties. Elisp in particular is subject to many of the same factors that
influenced, for example, modern English, including both partial embrace and
partial rejection of historical artifacts, adjustments based on common
errors, eras of "fashion" (where acceptible uses shift over time), and
dialects, creoles, and pidgins (ESE versus Americanized spoken English). I
studied both computer science and linguistics in the past, and I believe
this entirely explains why some lisps have/prefer "first" and "rest" while
others "car" and "cdr". In this case, nobody is proposing to get rid of the
latter, for either regular or irregular verbs. There is, however, a
suggestion ("It's a shame...") that elisp might be improved by some careful
application of additional words for concepts that don't seem to be core
enough to be irregular (that is, that aren't so common that everyone has
already internalized the irregular forms), as evidinced by the popularity
_amoung new speakers_ of libraries that add such regularity, even where
irregular forms already exist (dash.el, seq.el, s.el, map.ap, f.el, etc.).
Specific examples were brought up not as proposals to change code, but as
an explanitory aid in response to a direct request for such.

Addressing the point, part two:
"There are only two hard things in computer science: cache invalidation and
naming things."

I hope this helps,
~Chad.

P.S. I actually prefer the alternative formulation: "There are only two
hard things in computer science: cache invalidation, naming things, and off
by one errors."

[-- Attachment #2: Type: text/html, Size: 5219 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 30.04.2020 22:34, Philippe Vaucher wrote:
> - I propose to alias (not rename) existing functions dealing with files 
> to start with file-

'M-x report-emacs-bug' with a list of proposed aliases might speed this 
discussion along.

> For example s.el contains a lot of IMHO obvious 
> functions that emacs could include easily under a proper namespace that 
> would probably not offend anyone

Indeed, probably not. Especially if those "obvious" functions are 
something you really use in your code.

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

In addition to C-h d, perhaps apropos and its variants should find
'assq' when you search for 'alist'.

It would not be hard to make a feature to do this sort of thing
and handle it in apropos_accum.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Please, everyone, let's presume that everyone in this discussion is trying
to help us do the right thing.  Please don't attack people or be sacrastic.

Please review the Kind Communication Guidelines, and try to think
about them so we can be more kind to each other.  See
https://gnu.org/philosophy/kind-communication.html.  That way, we can
have a useful discussion and reach a good conclusion.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Starting from minute 3:00 you will regularly see Transient buffers in
  > use, popping up at the bottom of the frame, showing menus of commands
  > and the key sequences which invoke them.

Thanks, but I can't follow that.  Things flash on the screen, showing
lots of text I can hardly see (it is small print), and I have no idea
what it is doing or why.

I can't learn the details of using a package that way.

Anyway, the details are not what I need to learn.
What I want to understand is the basic purpose and use of Transient.

Would someone like to tell me in 10 lines
whet job Transient does, and why it is useful?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Stefan Monnier]

> Renaming them all might be a difficult discussion.

Fully agreed.
But that doesn't preclude trying to take care of a few simple cases.

I think `file-name-` and `process-` are good starting points.

If the result is disappointing, maybe we'll stop there.


        Stefan

Re: [ELPA] New package: transient

[Stefan Monnier]

> I don't know. I've never had an occasion to use this function. All I can say
> is that with fido-mode on (or with any of the packages like Ivy or Helm that
> provide fuzzy matching) its discoverability is not much of a problem.

But then you have the reverse problem: after typing `file-name` in
fido-mode you get too many false-positive for functions which aren't
"manipulating file names" but merely return a file-name.


        Stefan

Re: [ELPA] New package: transient

[Phil Sainty]

On 2020-05-01 14:52, Richard Stallman wrote:
> What I want to understand is the basic purpose and use of Transient.
> 
> Would someone like to tell me in 10 lines
> whet job Transient does, and why it is useful?

It is a fancy visual keymap.

It provides visual (but keyboard-driven) menus for invoking commands;
and also provides an interface for interactively specifying *arguments*
to pass to those commands, all from within the same menu.

The first aspect is like prefix key bindings, but with all of the keys
under the prefix being presented visually in a friendly format, with
descriptive labels, so that you can see at a glance what the possible
commands are, and which keys invoke them.

The second aspect is like a *much* fancier notion of prefix arguments,
where you can interactively (but optionally) specify the arguments you
wish to pass to the command you are about to select (and they are again
all labelled clearly, to help you understand what each one does).

It's useful because it's a very efficient and user-friendly interface
for invoking complex commands with arbitrary interactive arguments.


> Thanks, but I can't follow that.  Things flash on the screen, showing
> lots of text I can hardly see (it is small print), and I have no idea
> what it is doing or why.

Ok, if you freeze that video at 3:50 then you are looking at a frame
where the bottom window is displaying an active Transient buffer, and
I'll use that example as context...

The example is for performing various "git commit" commands.  It was
opened by typing "c" from a Magit buffer.  The command keys under that
prefix are shown at the bottom: (c, e, f, F, w, s, S, a, A), and
typing one of those will close the window and invoke the associated
command.  So typing "c c" will firstly open this Transient window, and
then close it and invoke the Magit command for a basic "git commit".

The "Arguments" list at the top shows key sequences beginning with "-"
(-a, -e, -v, -n, -R, -A, -s, -C), and typing any of those will configure
an argument for the command.  So in a Magit buffer, typing "c -s -e s"
would open this Transient window, then enable the "--signoff" argument,
then enable the "--allow-empty" option, and finally close the window
and invoke the Magit command for creating a git squash commit using the
selected arguments.  The arguments can be set in any sequence, until the
user types one of the command keys at the bottom, and highlighting is
employed to show which arguments are enabled.

Some arguments require user input, such as "--author=", so if the user
types "-A" they will be prompted in the minibuffer to enter the author
value.


-Phil

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Thu, 30 Apr 2020 22:49:35 -0400
> 
> In addition to C-h d, perhaps apropos and its variants should find
> 'assq' when you search for 'alist'.

When I suggested to use C-h d, the response was that this (or the
equivalent index-search in Info) is not the solution being sought.  So
I see no reason to extend facilities that will not help improve the
situation for people who think the C-h family of the commands is not
the right way to solve the problems they are reporting, because we'd
end up with a command that no one uses.

OTOH, we may wish to improve C-h d or apropos, for those who do use
it, by, for example, adding a facility to request the list of
functions and variables that have the first line of their doc string
match the specified regexp.  But that would be an independent idea,
not related to the current discussion.  I'm not aware of any requests
for such enhancements, FWIW, so I'm not sure they are worth our while.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > Yes, you're right sorry I was steaming. The fact that Alan Mackenzie
> > never apologized for his ugly behavior left me with a taste of revenge,
> > I'd fix that.
>
> First of all, let's note that your English is so good that you're either
> a native speaker of it (as I am), or might as well be.
>

Thanks for the compliment. My monther tongue is french, my mother is german
so I was more enclined toward german when younger.

I learnt english at school and did a 3 months solo-trip in australia where
I had this epiphany where english "clicked" and started to think in
english, so yes because of that I'm able to switch my brain to english mode
pretty easily and because I code and read in english every day this is more
or less kept up to date all the time.

That said,  I'm sure you'll find frenchism in many of my sentences ;-)

Also when I think in english I tend to cut much more corners than in
french, given it's a more technical straight-to-the-point language. Maybe
it's harder to be nuanced in english than in french?


> You know full well the difference between saying "we CAN make aliases to
> the old names" and "we COULD make aliases to the old names".  You wrote
> the first, thus suggesting you were about to stomp ahead and do it.
>

I both french and english I don't find this distinction very important. I
understand it's important for you so yes, I should have said "could". But
for me, "can" it itself implies a possibility. Also note that this was a
followup to another message where we explored what could be done, it was
not my main argument nor a proposal.



> You also understand full well the difference between "never apologized"
> and "hasn't apologized".  So you reject any apology from me in advance,
> because you didn't get it within your own rather tight time scale.  I'll
> apologise anyway.
>

I'm surprised with this one... In french we'd say "Jusqu'à présent, il ne
s'est jamais excusé.". Hum yes, ok the "jamais" is maybe a but superfluous,
"Il ne s'est pas excusé" is better.

When I wrote that I had in mind that you sent several messages further
holding your position instead of simply admiting that you overreacted, and
that a little sign in that direction would do wonders.

Now that you have done it we are fine, thanks for that.



> My post, the objectionable one, opened up a debate which had to take
> place, and might well not have done so without it.  You weren't the only
> person who was "steaming".  What I saw was a relative newcomer to the
> group (sorry, I still don't know your past and present) proposing to turn
> Emacs Lisp upside down for some uncertain benefit on an uncertain
> timescale, and not about to wait on any objections.
>

I understand I might have appeared as proposing to turn Emacs Lisp upside
down, sorry for not being clear enough.



> My thanking you this morning for your response was quite sincere.  You
> could quite easily have just ignored my post.
>
> Nevertheless, I apologise for that post (not for my "behavior"), both to
> you and to the group, in that it was too personal and too aggressive, and
> imputed motives to yourself which were unjustified.


Thanks! Glad we leveled it out.

Philippe

[-- Attachment #2: Type: text/html, Size: 4550 bytes --]

Re: [ELPA] New package: transient

[Kévin Le Gouguec]

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

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Starting from minute 3:00 you will regularly see Transient buffers in
>   > use, popping up at the bottom of the frame, showing menus of commands
>   > and the key sequences which invoke them.
>
> Thanks, but I can't follow that.  Things flash on the screen, showing
> lots of text I can hardly see (it is small print), and I have no idea
> what it is doing or why.
>
> I can't learn the details of using a package that way.
>
> Anyway, the details are not what I need to learn.
> What I want to understand is the basic purpose and use of Transient.
>
> Would someone like to tell me in 10 lines
> whet job Transient does, and why it is useful?

In addition to Phil's summary, and tying in with the other thread on the
discoverability of outline-mode's bindings, here is a hastily made-up
hypothetical transient command for outline-mode:

(define-transient-command outline-menu ()
  "Show menu for selective display."
  [["Show"
    ("a" "all" outline-show-all)
    ("e" "entry" outline-show-entry)
    ("i" "children" outline-show-children)
    ("k" "branches" outline-show-branches)
    ("s" "subtree" outline-show-subtree)]
   ["Hide"
    ("c" "entry" outline-hide-entry)
    ("d" "subtree" outline-hide-subtree)
    ("l" "leaves" outline-hide-leaves)
    ("o" "other" outline-hide-other)
    ("q" "sublevels" outline-hide-sublevels)
    ("t" "body" outline-hide-body)]])

After evaluating this form, if I then visit e.g. NEWS and 

(local-set-key (kbd "C-c @") 'outline-menu)

Then "C-c @" spawns a menu at the bottom of the frame:


[-- Attachment #2: transient-ouline-example.png --]
[-- Type: image/png, Size: 257611 bytes --]

[-- Attachment #3: Type: text/plain, Size: 600 bytes --]


From there, I can run the command I am interested in with a single
keystroke, and the transient menu disappears.  Overall it's pretty
unobtrusive[1], so once the command makes it to muscle memory it's
virtually indistinguishable from just running "C-c @ <key>" without
pause.

This is a pretty trivial example; see Phil's answer for more interesting
features (e.g. providing arguments to commands).


[1] Unlike say C-h b or C-h m, which 1. takes a whole window, 2. I have
    to scroll through if the key I'm interested in isn't featured in
    what's initially displayed, 3. I must quit manually.

Re: [ELPA] New package: transient

[Clément Pit-Claudel]

On 01/05/2020 06.40, Kévin Le Gouguec wrote:
> Richard Stallman <rms@gnu.org> writes:
>> Would someone like to tell me in 10 lines
>> whet job Transient does, and why it is useful?
> 
> In addition to Phil's summary, and tying in with the other thread on the
> discoverability of outline-mode's bindings, here is a hastily made-up
> hypothetical transient command for outline-mode:

Also, to get a sense of what transient feels like, you can try typing `h` in list-packages, which has its own custom implementation of a popup window.

Re: [ELPA] New package: transient

[Dmitry Gutov]

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

On 01.05.2020 06:15, Stefan Monnier wrote:
> But then you have the reverse problem: after typing `file-name` in
> fido-mode you get too many false-positive for functions which aren't
> "manipulating file names" but merely return a file-name.

That's a fair point, but still the discoverability is not too bad. Given 
weighted sorting, the relevant functions are mostly at the top, see the 
screenshot.

Although we might want to look into why backup-file-name-p is sorted 
before file-name-quoted-p.

[-- Attachment #2: Screenshot from 2020-05-01 18-28-36.png --]
[-- Type: image/png, Size: 320984 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

> On 01.05.2020 06:15, Stefan Monnier wrote:
> > But then you have the reverse problem: after typing `file-name` in
> > fido-mode you get too many false-positive for functions which aren't
> > "manipulating file names" but merely return a file-name.
>
> That's a fair point, but still the discoverability is not too bad. Given
> weighted sorting, the relevant functions are mostly at the top, see the
> screenshot.


I forgot to comment on the fido trick: I also use a completion mechanism
where it lists all function containing the search term, but as shown in
your screenshot the amount of filtering you have to do in your head in
order to have a plain list of functions relevant to what you search for is
too high in my opinion. I understand some people don't mind it but I see it
as unnecessary thinking that a consistant namespace would solve. That'd
mean search for `^file-name-` and have the curated list directly.

Philippe

[-- Attachment #2: Type: text/html, Size: 1249 bytes --]

Re: [ELPA] New package: transient

[João Távora]

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

On Wed, Apr 29, 2020, 14:32 Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>  things (e.g. add a `list` package
> where all the list functions get a new name using the `list` prefix, or
> add a `process` package were all the process related primitives are
> given a "process-"prefix, ...).
>

Ok to the others, but please don't add a `list` package. It will make the
Lisp gods cry. I don't have any better arguments :)

João

>

[-- Attachment #2: Type: text/html, Size: 995 bytes --]

Re: [ELPA] New package: transient

[Stefan Monnier]

>>  things (e.g. add a `list` package where all the list functions get
>> a new name using the `list` prefix, or add a `process` package were
>> all the process related primitives are given a "process-"prefix,
>> ...).
> Ok to the others, but please don't add a `list` package. It will make the
> Lisp gods cry. I don't have any better arguments :)

FWIW, I also think `list` above was a poor choice of example (not only
because of the baggage of history, but also because Lisp's lists are
really just a generic low-level data structure used for all kinds of
things besides actual lists, so it's the typical example where
a classification can't be satisfactory).

`process` is much more likely to lead to a good solution.


        Stefan

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Also, to get a sense of what transient feels like, you can try
  > typing `h` in list-packages, which has its own custom
  > implementation of a popup window.

'h' looks useful and clear.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Philippe was somewhat overeager in assuming that his proposal would
be adopted.  But that's not mean, only enthusiastic.

So if you disagree with such eagerness, please don't make it personal.

It was good that you apologized for the tone of your reaction.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > When I suggested to use C-h d, the response was that this (or the
  > equivalent index-search in Info) is not the solution being sought.

Why does it fail to do the job?
-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The "Arguments" list at the top shows key sequences beginning with "-"
  > (-a, -e, -v, -n, -R, -A, -s, -C), and typing any of those will configure
  > an argument for the command.  So in a Magit buffer, typing "c -s -e s"
  > would open this Transient window, then enable the "--signoff" argument,
  > then enable the "--allow-empty" option, and finally close the window
  > and invoke the Magit command for creating a git squash commit using the
  > selected arguments.

Now I understand, and it makes sense.  I like it.

Those "arguments" are comparable to what we call options, in shell
commands -- not to the arguments.  It seems to me that calling them
"options" would increase overall coherence.  What do you think of
this?

It occurs to me that this might be a good way to present menu bar menus.
Also, M-! could use this to select options for shell commands.
What do you think of this?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > application of additional words for concepts that don't seem to be core
  > enough to be irregular (that is, that aren't so common that everyone has
  > already internalized the irregular forms), as evidinced by the popularity
  > _amoung new speakers_ of libraries that add such regularity, even where
  > irregular forms already exist (dash.el, seq.el, s.el, map.ap, f.el, etc.).
  > Specific examples were brought up not as proposals to change code, but as
  > an explanitory aid in response to a direct request for such.

I think that is a  valid way to understand the issue.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > If we decide the answer is yes (as advised by the coding conventions) we
  > could start by simply aliasing the existing API that does not follow this
  > convention. That'd mean `copy-alist` would be aliased as `alist-copy`, do
  > you think people would be strongly against this?

I think there is no need to rigidly put the crucial word 'alist'
at the start of the name.  Just having 'alist' in the function name
makes it easy enough to find that function.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[T.V Raman]

Richard Stallman <rms@gnu.org> writes:

1+ on both. I learnt transient by using magit and in that context, I
recognized the "arguments" as git command-line options, but I can see
how I would have been confused if I hadn't learnt transient in that
specific context.> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > The "Arguments" list at the top shows key sequences beginning with "-"
>   > (-a, -e, -v, -n, -R, -A, -s, -C), and typing any of those will configure
>   > an argument for the command.  So in a Magit buffer, typing "c -s -e s"
>   > would open this Transient window, then enable the "--signoff" argument,
>   > then enable the "--allow-empty" option, and finally close the window
>   > and invoke the Magit command for creating a git squash commit using the
>   > selected arguments.
>
> Now I understand, and it makes sense.  I like it.
>
> Those "arguments" are comparable to what we call options, in shell
> commands -- not to the arguments.  It seems to me that calling them
> "options" would increase overall coherence.  What do you think of
> this?
>
> It occurs to me that this might be a good way to present menu bar menus.
> Also, M-! could use this to select options for shell commands.
> What do you think of this?

-- 

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: tomas@tuxteam.de, emacs-devel@gnu.org
> Date: Fri, 01 May 2020 22:24:51 -0400
> 
>   > When I suggested to use C-h d, the response was that this (or the
>   > equivalent index-search in Info) is not the solution being sought.
> 
> Why does it fail to do the job?

It doesn't fail, but there are evidently users who want to have that
information without using the documentation features of Emacs, so any
solution based on C-h is not acceptable to them.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: dgutov@yandex.ru, jonas@bernoul.li, emacs-devel@gnu.org,
> 	monnier@iro.umontreal.ca, adam@alphapapa.net, eliz@gnu.org,
> 	kyle@kyleam.com
> Date: Fri, 01 May 2020 22:27:47 -0400
> 
> I think there is no need to rigidly put the crucial word 'alist'
> at the start of the name.  Just having 'alist' in the function name
> makes it easy enough to find that function.

Not if you type "alist- TAB" and expect to see that function in the
list of completion candidates.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
>   > If we decide the answer is yes (as advised by the coding conventions)
> we
>   > could start by simply aliasing the existing API that does not follow
> this
>   > convention. That'd mean `copy-alist` would be aliased as `alist-copy`,
> do
>   > you think people would be strongly against this?
>
> I think there is no need to rigidly put the crucial word 'alist'
> at the start of the name.  Just having 'alist' in the function name
> makes it easy enough to find that function.


This prevents me from searching for `^alist` and have the curated list of
all alist related functions.

With alist, searching for `.*alist.*`  is not so bad, but with `file-name`
the problem shows more clearly: you have a lot of results that you'd like
to ignore (functions from tramp, etc).

[-- Attachment #2: Type: text/html, Size: 1071 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> >   > When I suggested to use C-h d, the response was that this (or the
> >   > equivalent index-search in Info) is not the solution being sought.
> >
> > Why does it fail to do the job?
>
> It doesn't fail, but there are evidently users who want to have that
> information without using the documentation features of Emacs, so any
> solution based on C-h is not acceptable to them.
>

While there might be some users who think that way, my workflow is mainly
to use `C-h f` to find the help of the function I'm interested in. This is
where not properly namespaced libraries are hurting me.

`C-h d` or `apropos` is plan B, and then I have to filter what is relevant
and not, and also because the result set of `C-h d` is so big scrolling
inside my Emacs becomes sluggish, which is not pleasant. So usually a this
point I go online and search, and fall on Xah-Lee's page, EmacsWiki, or
stackoverflow.

[-- Attachment #2: Type: text/html, Size: 1195 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 10:09:36 +0200
> Cc: Richard Stallman <rms@gnu.org>, tomas@tuxteam.de, Emacs developers <emacs-devel@gnu.org>
> 
>  > Why does it fail to do the job?
> 
>  It doesn't fail, but there are evidently users who want to have that
>  information without using the documentation features of Emacs, so any
>  solution based on C-h is not acceptable to them.
> 
> While there might be some users who think that way, my workflow is mainly to use `C-h f` to find the help of
> the function I'm interested in. This is where not properly namespaced libraries are hurting me.
> 
> `C-h d` or `apropos` is plan B, and then I have to filter what is relevant and not, and also because the result
> set of `C-h d` is so big scrolling inside my Emacs becomes sluggish, which is not pleasant. So usually a this
> point I go online and search, and fall on Xah-Lee's page, EmacsWiki, or stackoverflow.

If I may: your strategy is sub-optimal.  When looking for a function
whose name you don't know, the first place to look is in the ELisp
manual.  Thus, for finding functions that deal with alists, the first
thing to try is "i alist RET" in the ELisp manual.  Here "alist" is
not a part of a function's name, it's a topic which you are looking
for.  That is much more efficient than the sequence you described
above, because we take special care of having meaningful topics in the
indices of the manual, precisely to help in such situations.  (And my
advice is to always have the ELisp manual shown in some frame on your
display, so that you don't even need to type "C-h i" etc. to get to
it.)

If you know _something_ about the function's name, then constructing a
proper regexp from what you know and using "C-u C-h a" might also be
efficient enough, especially if you cannot come up with a topic
specific enough to give to Info's 'i' command.

But at this point I'm completely confused about your central argument,
because my original mentioning of "C-h d" was regarded as missing the
point, and you objected to the very idea of searching the
documentation.  Quote:

>     I think "C-h d alist RET" is your friend.
> 
> You miss the central point of my argument. The problem is not that the doc is hard to find, it's that I *have* to find it to know which are the related functions.
> 
> It is much easier for the mind to think in terms of namespaces, here are examples from other languages:

So now I'm no confused because my conclusion from the above was that
you don't want to use the documentation features, but you now
evidently disagreed with that conclusion.  Sorry.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Date: Sat, 02 May 2020 12:05:22 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: tomas@tuxteam.de, rms@gnu.org, emacs-devel@gnu.org
> 
> >  > Why does it fail to do the job?
> > 
> >  It doesn't fail, but there are evidently users who want to have that
> >  information without using the documentation features of Emacs, so any
> >  solution based on C-h is not acceptable to them.
> > 
> > While there might be some users who think that way, my workflow is mainly to use `C-h f` to find the help of
> > the function I'm interested in. This is where not properly namespaced libraries are hurting me.

And if it wasn't clear: "C-h f" is for looking up a function whose
name you already know.  Which is AFAIU not the case in your original
use case.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> >  It doesn't fail, but there are evidently users who want to have that
> >  information without using the documentation features of Emacs, so any
> >  solution based on C-h is not acceptable to them.
> >
> > While there might be some users who think that way, my workflow is
> mainly to use `C-h f` to find the help of
> > the function I'm interested in. This is where not properly namespaced
> libraries are hurting me.
> >
> > `C-h d` or `apropos` is plan B, and then I have to filter what is
> relevant and not, and also because the result
> > set of `C-h d` is so big scrolling inside my Emacs becomes sluggish,
> which is not pleasant. So usually a this
> > point I go online and search, and fall on Xah-Lee's page, EmacsWiki, or
> stackoverflow.
>
> If I may: your strategy is sub-optimal.  When looking for a function
> whose name you don't know, the first place to look is in the ELisp
> manual.  Thus, for finding functions that deal with alists, the first
> thing to try is "i alist RET" in the ELisp manual.  Here "alist" is
> not a part of a function's name, it's a topic which you are looking
> for.  That is much more efficient than the sequence you described
> above, because we take special care of having meaningful topics in the
> indices of the manual, precisely to help in such situations.  (And my
> advice is to always have the ELisp manual shown in some frame on your
> display, so that you don't even need to type "C-h i" etc. to get to
> it.)
>

Let's try again why this is not an optimal strategy for me:

Searching the manual lands me on
https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html.
This is all good, but most of the time I don't need all this introduction,
I just really need a curated list of the function names related to the
topic I'm searching. When learning this page is really useful but when
trying to quickly find what function you need, this page is 95% noise. What
happens is that I'll look at each "-- function" part and enter a loop of
"not that, skip paragraph" until I find the function I want.

If I take that entry manual and then toggle read only and then "M-x
keep-lines -- function" I end up with:

 -- Function: assoc key alist &optional testfn
 -- Function: rassoc value alist
 -- Function: assq key alist
 -- Function: alist-get key alist &optional default remove testfn
 -- Function: rassq value alist
 -- Function: assoc-default key alist &optional test default
 -- Function: copy-alist alist
 -- Function: assq-delete-all key alist
 -- Function: assoc-delete-all key alist
 -- Function: rassq-delete-all value alist

That's what I would like to get out of the manual easily. Note that if
these were properly namespaced I'd just use "C-h f alist" and be done with
it. But keep in mind "alist" is a poor example, regexp are a much better
example I think. Let me illustrate.

Over 95% of my documentation search is just that (quickly looking at a list
of functions). I'm fluent in many languages already, I don't need a
regexp (or whatever) introduction with detailed explanations. I just want
to find how to do a regexp match and extract the results. When I fall on
https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html it
takes way too much reading to find `string-match`, and this page doesn't
even mention `match-string`! That means I have to do another search and
find
https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html.
I'm sure that if you put yourself in my shoes you'd be able to understand
my frustration.

In the other languages I use (C++, Ruby) I never have that frustration. It
looks like that in Clojure or Scheme I'd be happy too. Maybe it's just me
and I have a problem with Emacs Lisp, but from looking at the s.el, f.el
and dash.el community I believe we are a significant minority.



> But at this point I'm completely confused about your central argument,
> because my original mentioning of "C-h d" was regarded as missing the
> point, and you objected to the very idea of searching the
> documentation.  Quote:
>
> >     I think "C-h d alist RET" is your friend.
> >
> > You miss the central point of my argument. The problem is not that the
> doc is hard to find, it's that I *have* to find it to know which are the
> related functions.
> >
> > It is much easier for the mind to think in terms of namespaces, here are
> examples from other languages:
>
> So now I'm no confused because my conclusion from the above was that
> you don't want to use the documentation features, but you now
> evidently disagreed with that conclusion.  Sorry.
>

What I said here is that I have to find that manual entry and read 300
lines of text when I could have had a list of 10 lines to start with. The
manual has the information I want, just way too verbose.

Also remember that you were talking about "C-h d alist", I think you missed
my further explanations of that point, allow me quote myself again:

On Wed, Apr 29, 2020 at 3:19 PM Philippe Vaucher <philippe.vaucher@gmail.com>
wrote:
>>
>> I think "C-h d alist RET" is your friend.
>
> To further illustrate my point, this doesn't lists `assq` or `assoc`,
both functions being indispensable when using alists.

My point is that "C-h d alist" is not sufficient to find assq or assoc,
thus while a useful tool it's not very efficient. There's also a lot of
noise on that listing when searching something as generic as "alist". I
simply want a mechanism where I'm close to 100% certain that I have the
whole list of functions related to a topic.

Maybe I'm asking for too much, or maybe my way of functionning is "wrong"
in the Emacs Lisp world. I'm curious, please tell me more about how you
function, maybe Emacs Lisp is your most used language so you know it all by
heart? How often do you popup the manual, and how often do you use "C-h f"?

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 7356 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > > While there might be some users who think that way, my workflow is
> mainly to use `C-h f` to find the help of
> > > the function I'm interested in. This is where not properly namespaced
> libraries are hurting me.
>
> And if it wasn't clear: "C-h f" is for looking up a function whose
> name you already know.  Which is AFAIU not the case in your original
> use case.
>

My original use case is: I want to copy an association list, I know the
function will probably have "copy" in its name and "alist", let's C-h f for
"alist TAB" and fail because no results. Start again with "copy TAB" and
filter the lots of "copy-*" function until I find copy-alist. Now imagine
if this particual function was named "asscpy" instead how frustrated I'd be
:-) Also imagine how self-documenting and self-discoverable Emacs Lisp
would be if things where properly namespaced, like we ask for all packages
to be on MELPA/ELPA and friends. Also autocompletion becomes much easier
because you type "(alist-c" and it proposes alist-copy straight away. Sorry
I'm a dreamer that like predictability & consistency :-)

As said earlier, probably that my way of thinking is not common around
here, but I'd not be surprised if it was common for many developpers, maybe
outside Emacs Lisp.

Philippe

[-- Attachment #2: Type: text/html, Size: 1677 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 12:11:10 +0200
> Cc: tomas@tuxteam.de, Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
>  And if it wasn't clear: "C-h f" is for looking up a function whose
>  name you already know.  Which is AFAIU not the case in your original
>  use case.
> 
> My original use case is: I want to copy an association list, I know the function will probably have "copy" in its
> name and "alist", let's C-h f for "alist TAB" and fail because no results. Start again with "copy TAB" and filter
> the lots of "copy-*" function until I find copy-alist.

"C-u C-h a copy alist RET" finds that function as the single hit.  As
does "C-u C-h a alist copy RET".

> Now imagine if this particual function was named "asscpy"
> instead how frustrated I'd be :-)

You will be frustrated because you use the wrong command.  "C-h f" is
not your friend unless you have a very good idea of the function's
name.  That's why "apropos" family of commands were invented: to help
you find something you don't know by name.  There's a best tool for
each job, and "C-h f" is not a good tool for this job.

But I already said that, several times.  And since you still disagree,
then I must insist that my response to Richard was spot-on: he asked
why doesn't "C-h d" do the job, and my response was, in a nutshell,
that what "C-h d" does is not relevant for you and other users who
think and are accustomed to work like you do.  You disagreed with my
conclusion, but we now made one more full circle, and established that
my conclusion was correct after all.

> Also imagine how self-documenting and self-discoverable Emacs Lisp would
> be if things where properly namespaced, like we ask for all packages to be on MELPA/ELPA and friends.

I'm not objected to have aliases that would make it easier to find out
the function's name using simple completion, but I think you greatly
overestimate the usefulness of that in many practical situations.
Meanwhile there are existing features designed specifically for these
use cases, which do their job much more efficiently _today_, and you
choose to disregard them or treat them as second-class citizens.  I
think it's a mistake, but I can only make suggestions and point out
that those features do exist.

> As said earlier, probably that my way of thinking is not common around here, but I'd not be surprised if it was
> common for many developpers, maybe outside Emacs Lisp.

My earnest advice for those developers is to try the features I
mentioned, they might find them useful in situations similar to the
one you described, and they might then decide to use them more than
what they do today.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 10:53 AM Philippe Vaucher
<philippe.vaucher@gmail.com> wrote:

> If I take that entry manual and then toggle read only and then "M-x keep-lines -- function" I end up with:
>
>  -- Function: assoc key alist &optional testfn
>  -- Function: rassoc value alist
>  -- Function: assq key alist
>  -- Function: alist-get key alist &optional default remove testfn
>  -- Function: rassq value alist
>  -- Function: assoc-default key alist &optional test default
>  -- Function: copy-alist alist
>  -- Function: assq-delete-all key alist
>  -- Function: assoc-delete-all key alist
>  -- Function: rassq-delete-all value alist
>
> That's what I would like to get out of the manual easily.

If I may, it sounds like you have described a process which a (small) GNU Elpa
package could replicate easily.  I for one would install it.  In the Common Lisp
hyperspec pages with this kind of information are found in "the string
dictionary",
"the sequences dictionary".  I think demanding namespacing for discoverability
is mixing up two not entirely orthogonal but also not entirely dependent things.

João

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 11:53:07 +0200
> Cc: Richard Stallman <rms@gnu.org>, tomas@tuxteam.de, Emacs developers <emacs-devel@gnu.org>
> 
> Searching the manual lands me on
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html. This is all good, but
> most of the time I don't need all this introduction, I just really need a curated list of the function names related
> to the topic I'm searching. When learning this page is really useful but when trying to quickly find what
> function you need, this page is 95% noise. What happens is that I'll look at each "-- function" part and enter a
> loop of "not that, skip paragraph" until I find the function I want. 
> 
> If I take that entry manual and then toggle read only and then "M-x keep-lines -- function" I end up with:
> 
>  -- Function: assoc key alist &optional testfn
>  -- Function: rassoc value alist
>  -- Function: assq key alist
>  -- Function: alist-get key alist &optional default remove testfn
>  -- Function: rassq value alist
>  -- Function: assoc-default key alist &optional test default
>  -- Function: copy-alist alist
>  -- Function: assq-delete-all key alist
>  -- Function: assoc-delete-all key alist
>  -- Function: rassq-delete-all value alist
> 
> That's what I would like to get out of the manual easily.

I fail to see how will the above list be useful, if you know nothing
about the function's name.  E.g., a newbie that has no previous Lisp
baggage will never be able to guess that assq should have anything to
do with association lists.  They will need the text keep-lines removes.

So maybe you should make your argument more concrete by saying what
you did know in this case.  My proposal to use Info-index was based on
the assumption that you knew nothing except that the function was
about alists.  In another message you said that you actually knew the
function will include "copy" and "alist" somewhere in its name, so I
suggested a different command that is better for that use case.

IOW, for each use case there's the best tool, and there are others
which are good, but not the best.  For example, even if you did go to
the above manual section, why would you need to generate the list of
functions?  "C-s copy" finds copy-alist as the first hit.  So even
being presented with a relatively long (290 lines) section in the
manual, finding what you want in that section is a matter of seconds.
I fail to see the problem.

> Over 95% of my documentation search is just that (quickly looking at a list of functions). I'm fluent in many
> languages already, I don't need a regexp (or whatever) introduction with detailed explanations. I just want to
> find how to do a regexp match and extract the results. When I fall on
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html it takes way too much
> reading to find `string-match`, and this page doesn't even mention `match-string`! That means I have to do
> another search and find
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html. I'm sure that if you
> put yourself in my shoes you'd be able to understand my frustration.

I cannot put myself in your shoes unless you describe the situation
more completely.  Specifically, what _did_ you know about string-match
and match-string, and which topics relevant to these would be in your
opinion relevant for looking up those functions?  Then we could
continue having a useful discussion, one where the results are that we
improve Emacs, including in ways other than those you thought about.

E.g., based on what _I_ have in mind in the above situation, I'd first
try "i regexp TAB" in the ELisp manual, see nothing pertinent, then
try "match TAB", and voila! I see match-data and match-string.

>  So now I'm no confused because my conclusion from the above was that
>  you don't want to use the documentation features, but you now
>  evidently disagreed with that conclusion.  Sorry.
> 
> What I said here is that I have to find that manual entry and read 300 lines of text when I could have had a
> list of 10 lines to start with. The manual has the information I want, just way too verbose.

No need to read the entire section, just use C-s to search for what
you want.

> Also remember that you were talking about "C-h d alist", I think you missed my further explanations of that
> point, allow me quote myself again:
> 
> On Wed, Apr 29, 2020 at 3:19 PM Philippe Vaucher <philippe.vaucher@gmail.com> wrote:
> >>
> >> I think "C-h d alist RET" is your friend.
> >
> > To further illustrate my point, this doesn't lists `assq` or `assoc`, both functions being indispensable when
> using alists.
> 
> My point is that "C-h d alist" is not sufficient to find assq or assoc, thus while a useful tool it's not very
> efficient.

You don't know me very well, do you?  Try "C-h d alist" in a recent
development snapshot, and I think you will see those functions there.
I fixed that within 5 minutes of your saying that those functions
couldn't be found by "C-h d".

> There's also a lot of noise on that listing when searching something as generic as "alist". I simply
> want a mechanism where I'm close to 100% certain that I have the whole list of functions related to a topic.

That depends on what you know about the function; see my earlier
response about "C-h a" and in particular about finding a function
about which you know that its name should include "copy" and "alist".

> Maybe I'm asking for too much, or maybe my way of functionning is "wrong" in the Emacs Lisp world. I'm
> curious, please tell me more about how you function, maybe Emacs Lisp is your most used language so you
> know it all by heart? How often do you popup the manual, and how often do you use "C-h f"?

I think by now you should already know the answer.  I have the ELisp
manual open in a dedicated frame at all times, and I consult it all
the time.  I use "C-h f" only if I think I know the function's name
quite accurately, and the same with "C-h v" and variables.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > My original use case is: I want to copy an association list, I know the
> function will probably have "copy" in its
> > name and "alist", let's C-h f for "alist TAB" and fail because no
> results. Start again with "copy TAB" and filter
> > the lots of "copy-*" function until I find copy-alist.
>
> "C-u C-h a copy alist RET" finds that function as the single hit.  As
> does "C-u C-h a alist copy RET".
>

Right, that works well. Thanks. It's not the most obvious keybinding but
"C-h d copy alist" also works.



> > Now imagine if this particual function was named "asscpy"
> > instead how frustrated I'd be :-)
>
> You will be frustrated because you use the wrong command.  "C-h f" is
> not your friend unless you have a very good idea of the function's
> name.  That's why "apropos" family of commands were invented: to help
> you find something you don't know by name.  There's a best tool for
> each job, and "C-h f" is not a good tool for this job.
>
> But I already said that, several times.  And since you still disagree,
> then I must insist that my response to Richard was spot-on: he asked
> why doesn't "C-h d" do the job, and my response was, in a nutshell,
> that what "C-h d" does is not relevant for you and other users who
> think and are accustomed to work like you do.  You disagreed with my
> conclusion, but we now made one more full circle, and established that
> my conclusion was correct after all.
>

I think we are mixing two concepts here. To search for a single function,
where you already know the keywords, yes "C-h d" works. To get a curated
list of the API of a topic, not so much. Because my examples mix both
finding a specific function and getting the curated list, I guess we were
each talking about the specific function example and I want talking about
the curated list.

I still think "C-h d alist", because it does not give me assq and assoc is
not doing a good job.

Because alist is controversial let's take "C-h d regexp match": it does not
give me string-match nor match-string. If I search for "regex match" then I
find match-string.

But overall I understand your point better now, you are not supposed to use
"C-h d" to get a curated list of the api of a topic, it's just to find a
single function. For that I agree it's a good tool.



> > Also imagine how self-documenting and self-discoverable Emacs Lisp would
> > be if things where properly namespaced, like we ask for all packages to
> be on MELPA/ELPA and friends.
>
> I'm not objected to have aliases that would make it easier to find out
> the function's name using simple completion, but I think you greatly
> overestimate the usefulness of that in many practical situations.
> Meanwhile there are existing features designed specifically for these
> use cases, which do their job much more efficiently _today_, and you
> choose to disregard them or treat them as second-class citizens.  I
> think it's a mistake, but I can only make suggestions and point out
> that those features do exist.
>

I'm still not very satisfied about the tools you showed for listing an
overview of the API to manipulate regexp, or files, or processes (etc).
What you are basically saying is that wanting to have this overview is
overrated, but for me it helps me understand the landscape of how the API
works and is designed. What functions would be available should I need them
in the future, what parts is missing, etc.

For now the only tool I have is the manual page with "M-x keep-lines --
function".



> > As said earlier, probably that my way of thinking is not common around
> here, but I'd not be surprised if it was
> > common for many developpers, maybe outside Emacs Lisp.
>
> My earnest advice for those developers is to try the features I
> mentioned, they might find them useful in situations similar to the
> one you described, and they might then decide to use them more than
> what they do today.
>

I'll certainly start to use it more.

Thanks,
Philippe

[-- Attachment #2: Type: text/html, Size: 5262 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> I think we are mixing two concepts here. To search for a single function,
> where you already know the keywords, yes "C-h d" works. To get a curated
> list of the API of a topic, not so much. Because my examples mix both
> finding a specific function and getting the curated list, I guess we were
> each talking about the specific function example and I want talking about
> the curated list.
>

Sorry this is unclear, what I meant is that you said C-h d works (because
of the "copy alist" example) and I said it didn't (because it does not give
me a curated list). We were just talking about different aspects.

Philippe

>

[-- Attachment #2: Type: text/html, Size: 1072 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > If I take that entry manual and then toggle read only and then "M-x
> keep-lines -- function" I end up with:
> >
> >  -- Function: assoc key alist &optional testfn
> >  -- Function: rassoc value alist
> >  -- Function: assq key alist
> >  -- Function: alist-get key alist &optional default remove testfn
> >  -- Function: rassq value alist
> >  -- Function: assoc-default key alist &optional test default
> >  -- Function: copy-alist alist
> >  -- Function: assq-delete-all key alist
> >  -- Function: assoc-delete-all key alist
> >  -- Function: rassq-delete-all value alist
> >
> > That's what I would like to get out of the manual easily.
>
> If I may, it sounds like you have described a process which a (small) GNU
> Elpa
> package could replicate easily.  I for one would install it.  In the
> Common Lisp
> hyperspec pages with this kind of information are found in "the string
> dictionary",
> "the sequences dictionary".  I think demanding namespacing for
> discoverability
> is mixing up two not entirely orthogonal but also not entirely dependent
> things.


Interesting point. I think that could work, but wouldn't it be much easier
if the language itself was self-documenting?

Sure we can create indexes and manuals and all that, but I find it much
more logical for the language to simply self-index and self-document itself
by naming things "logically" in the language itself.

But yeah, you're right. Eventually either all of those who think like me
will create even more `s.el`, `f.el` and friends, or they'll write manual
helpers, or they'll simply give up.

Philippe

[-- Attachment #2: Type: text/html, Size: 2048 bytes --]

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 12:10 PM Philippe Vaucher
<philippe.vaucher@gmail.com> wrote:
>>
>> > If I take that entry manual and then toggle read only and then "M-x keep-lines -- function" I end up with:
>> >
>> >  -- Function: assoc key alist &optional testfn
>> >  -- Function: rassoc value alist
>> >  -- Function: assq key alist
>> >  -- Function: alist-get key alist &optional default remove testfn
>> >  -- Function: rassq value alist
>> >  -- Function: assoc-default key alist &optional test default
>> >  -- Function: copy-alist alist
>> >  -- Function: assq-delete-all key alist
>> >  -- Function: assoc-delete-all key alist
>> >  -- Function: rassq-delete-all value alist
>> >
>> > That's what I would like to get out of the manual easily.
>>
>> If I may, it sounds like you have described a process which a (small) GNU Elpa
>> package could replicate easily.  I for one would install it.  In the Common Lisp
>> hyperspec pages with this kind of information are found in "the string
>> dictionary",
>> "the sequences dictionary".  I think demanding namespacing for discoverability
>> is mixing up two not entirely orthogonal but also not entirely dependent things.
>
>
> Interesting point. I think that could work, but wouldn't it be much easier if the language itself was self-documenting?

Maybe, but that entails changing the language, by definition.  And you
will face resistance because languages are things people kinda grow
accustomed to.  Imagine if I told you the French language should now
also include all the words of Portuguese, because, you know, they're
just better. Even worse with macros. It's like I told you not only you
have to learn Portuguese words, but its grammar, too.

João




João

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 12:56:41 +0200
> Cc: tomas@tuxteam.de, Richard Stallman <rms@gnu.org>,
>  Emacs developers <emacs-devel@gnu.org>
> 
> I think we are mixing two concepts here. To search for a single function, where you already know the
> keywords, yes "C-h d" works. To get a curated list of the API of a topic, not so much.

That's why I proposed to have a variant of "C-h d" that would only
look in the arguments and in the first line of the doc string.  It
would produce less false positives.

> I still think "C-h d alist", because it does not give me assq and assoc is not doing a good job.

they do now.

> Because alist is controversial let's take "C-h d regexp match": it does not give me string-match nor
> match-string.

??? It does here.

> I'm still not very satisfied about the tools you showed for listing an overview of the API to manipulate regexp,
> or files, or processes (etc). What you are basically saying is that wanting to have this overview is overrated,
> but for me it helps me understand the landscape of how the API works and is designed. What functions
> would be available should I need them in the future, what parts is missing, etc.

For that, you should definitely read the manual, not just look at the
list of APIs.  A list of the APIs will not tell enough, especially if
you are coming to a language that has a long history, with such
idiosyncratic names as cdr and assq.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > Interesting point. I think that could work, but wouldn't it be much
> easier if the language itself was self-documenting?
>
> Maybe, but that entails changing the language, by definition.  And you
> will face resistance because languages are things people kinda grow
> accustomed to.  Imagine if I told you the French language should now
> also include all the words of Portuguese, because, you know, they're
> just better. Even worse with macros. It's like I told you not only you
> have to learn Portuguese words, but its grammar, too.
>

Well I propose to add new-style APIs. People can still use the old ones.

But yeah, I'm coming to the conclusion that even adding a new-style API is
too disruptive. If it happens It'll probably live outside of Emacs in MELPA.

I'm not sure I like this simplification, but there seem to be two
communities of Emacs users, the "traditional" one and the "github" one.
Both have their perspective on how things should be, and it seems that both
communities have trouble understanding how the other community function.

It's been several time now that the "github community" proposed changes
that looked "evident improvements" to them but got hit by a wall of
incomprehension/complexity (I'm not saying this proposal is one of them,
but what comes often is "why not gitlab? how come s.el is not in Emacs
core?", etc). I'm not sure if there is a way forward on this, it just is
that way. I hope that in the future we can understand each others better
and find good compromises quicker, without all the noise.

Kind regards,
Philippe

[-- Attachment #2: Type: text/html, Size: 1979 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > If I take that entry manual and then toggle read only and then "M-x
> keep-lines -- function" I end up with:
> >
> >  -- Function: assoc key alist &optional testfn
> >  -- Function: rassoc value alist
> >  -- Function: assq key alist
> >  -- Function: alist-get key alist &optional default remove testfn
> >  -- Function: rassq value alist
> >  -- Function: assoc-default key alist &optional test default
> >  -- Function: copy-alist alist
> >  -- Function: assq-delete-all key alist
> >  -- Function: assoc-delete-all key alist
> >  -- Function: rassq-delete-all value alist
> >
> > That's what I would like to get out of the manual easily.
>
> I fail to see how will the above list be useful, if you know nothing
> about the function's name.  E.g., a newbie that has no previous Lisp
> baggage will never be able to guess that assq should have anything to
> do with association lists.  They will need the text keep-lines removes.
>

But I'm not a newbie! I don't use Emacs lisp enough to remember all the
details all the time, but I know what I'm looking for when I see it.



> So maybe you should make your argument more concrete by saying what
> you did know in this case.  My proposal to use Info-index was based on
> the assumption that you knew nothing except that the function was
> about alists.  In another message you said that you actually knew the
> function will include "copy" and "alist" somewhere in its name, so I
> suggested a different command that is better for that use case.
>

Yes, there is a lot of different use cases. Sorry for that.



> IOW, for each use case there's the best tool, and there are others
> which are good, but not the best.  For example, even if you did go to
> the above manual section, why would you need to generate the list of
> functions?  "C-s copy" finds copy-alist as the first hit.  So even
> being presented with a relatively long (290 lines) section in the
> manual, finding what you want in that section is a matter of seconds.
> I fail to see the problem.
>

That's for the case where you search for "copy", yes. That does not cover
the "overview" aspect.



> > Over 95% of my documentation search is just that (quickly looking at a
> list of functions). I'm fluent in many
> > languages already, I don't need a regexp (or whatever) introduction with
> detailed explanations. I just want to
> > find how to do a regexp match and extract the results. When I fall on
> >
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html
> it takes way too much
> > reading to find `string-match`, and this page doesn't even mention
> `match-string`! That means I have to do
> > another search and find
> >
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html.
> I'm sure that if you
> > put yourself in my shoes you'd be able to understand my frustration.
>
> I cannot put myself in your shoes unless you describe the situation
> more completely.  Specifically, what _did_ you know about string-match
> and match-string, and which topics relevant to these would be in your
> opinion relevant for looking up those functions?  Then we could
> continue having a useful discussion, one where the results are that we
> improve Emacs, including in ways other than those you thought about.
>
> E.g., based on what _I_ have in mind in the above situation, I'd first
> try "i regexp TAB" in the ELisp manual, see nothing pertinent, then
> try "match TAB", and voila! I see match-data and match-string.
>

I'm not sure it'd be useful. I gave plenty of examples and at this point
either my way of functionning is broken or you simply never function like I
do so you don't see the problem.



> > My point is that "C-h d alist" is not sufficient to find assq or assoc,
> thus while a useful tool it's not very
> > efficient.
>
> You don't know me very well, do you?  Try "C-h d alist" in a recent
> development snapshot, and I think you will see those functions there.
> I fixed that within 5 minutes of your saying that those functions
> couldn't be found by "C-h d".
>

So, my point *was* valid two days ago. How many other topics of Emacs are
still affected tho?



> > Maybe I'm asking for too much, or maybe my way of functionning is
> "wrong" in the Emacs Lisp world. I'm
> > curious, please tell me more about how you function, maybe Emacs Lisp is
> your most used language so you
> > know it all by heart? How often do you popup the manual, and how often
> do you use "C-h f"?
>
> I think by now you should already know the answer.  I have the ELisp
> manual open in a dedicated frame at all times, and I consult it all
> the time.  I use "C-h f" only if I think I know the function's name
> quite accurately, and the same with "C-h v" and variables.
>

I'll try this for a while and see how it goes.

Philippe

[-- Attachment #2: Type: text/html, Size: 6737 bytes --]

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > I think we are mixing two concepts here. To search for a single
> function, where you already know the
> > keywords, yes "C-h d" works. To get a curated list of the API of a
> topic, not so much.
>
> That's why I proposed to have a variant of "C-h d" that would only
> look in the arguments and in the first line of the doc string.  It
> would produce less false positives.
>

Ok but that means it does not exist now, so that's why I say "C-h d" does
not work for me for all use cases right now. But ok we agree.



> > Because alist is controversial let's take "C-h d regexp match": it does
> not give me string-match nor
> > match-string.
>
> ??? It does here.


It's listed at the 1293th lines! I have to scroll for ages, while passing
by `magic-mode-regexp-match-limit` or `char-fold-to-regexp`. Surely this
cannot be a good solution.

Philippe

[-- Attachment #2: Type: text/html, Size: 1360 bytes --]

Re: [ELPA] New package: transient

[João Távora]

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

On Sat, May 2, 2020 at 12:40 PM Philippe Vaucher <philippe.vaucher@gmail.com>
wrote:
>>
>> > Interesting point. I think that could work, but wouldn't it be much
easier if the language itself was self-documenting?
>>
>> Maybe, but that entails changing the language, by definition.  And you
>> will face resistance because languages are things people kinda grow
>> accustomed to.  Imagine if I told you the French language should now
>> also include all the words of Portuguese, because, you know, they're
>> just better. Even worse with macros. It's like I told you not only you
>> have to learn Portuguese words, but its grammar, too.
>
>
> Well I propose to add new-style APIs. People can still use the old ones.

But they would have to learn to read programs in the new stuff, no?  I
never said you would be replacing words in French, just adding.

To be fair, in programming languages, one has to do that, with
libraries.  The finer point here is that you're asking for new words
for general purpose talk, not new words for a specific new subject,
like, say, nuclear frobnicators.  You'd certainly need new words for
that.

> But yeah, I'm coming to the conclusion that even adding a new-style
> API is too disruptive. If it happens It'll probably live outside of
> Emacs in MELPA.
>
> I'm not sure I like this simplification, but there seem to be two
> communities of Emacs users, the "traditional" one and the "github"
> one. Both have their perspective on how things should be, and it seems
> that both communities have trouble understanding how the other
> community function.

Yep. It's a simplification.  I use GitHub a lot (more than I wanted to).
It's the only social network I use, btw, because stuff actually gets
built there.

But indeed there is a kind of separation (though perhaps less bipolar
than you make it appear, and more of a spectrum).  I guess I was once in
the ruby-cool-kids-web-2.0-quick-google-ftw faction, if you understand
what I mean, but I got to learn the old-school ways of the manual and
Emacs -Q and now I really like them.  In 2006, I had a long
painstakingly crafted configuration that made Emacs behave like
Eclipse and I'm very happy to have rid myself of it (I do keep the smart
C-a though).  Nowadays, when I find an awkward part in Emacs I ask
myself: if people have been using this for so long, there _must_ be a
good reason for this interface.  If I don't find an obvious answer, I
ask here. And often, things do evolve.  But very often too, it was
indeed a pretty good interface to start with, I just wasn't aware of it.
Why wasn't I aware of it?  Well, indeed, Emacs could do a better job of
communicating its superior interfaces to the world, but we're
outnumbered against all those people that impatiently expect it to
behave like the cool VSCode rock star screencasts, just like I once did
about Eclipse.

João

[-- Attachment #2: Type: text/html, Size: 3362 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 13:47:35 +0200
> Cc: tomas@tuxteam.de, Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
>  > My point is that "C-h d alist" is not sufficient to find assq or assoc, thus while a useful tool it's not very
>  > efficient.
> 
>  You don't know me very well, do you?  Try "C-h d alist" in a recent
>  development snapshot, and I think you will see those functions there.
>  I fixed that within 5 minutes of your saying that those functions
>  couldn't be found by "C-h d".
> 
> So, my point *was* valid two days ago. How many other topics of Emacs are still affected tho?

I don't know.  I can promise that each topic that will be reported
with similar issues will be fixed very quickly.

>  I think by now you should already know the answer.  I have the ELisp
>  manual open in a dedicated frame at all times, and I consult it all
>  the time.  I use "C-h f" only if I think I know the function's name
>  quite accurately, and the same with "C-h v" and variables.
> 
> I'll try this for a while and see how it goes.

Thanks.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 13:52:09 +0200
> Cc: tomas@tuxteam.de, Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
>  > Because alist is controversial let's take "C-h d regexp match": it does not give me string-match nor
>  > match-string.
> 
>  ??? It does here.
> 
> It's listed at the 1293th lines! I have to scroll for ages, while passing by `magic-mode-regexp-match-limit` or
> `char-fold-to-regexp`. Surely this cannot be a good solution.

It can, if someone needs such a general search.  For looking up
functions, I think my proposal to look just in the arguments and the
first line of the doc string will be more efficient.

And index search in the ELisp manual is also a good tool in this case.

Re: [ELPA] New package: transient

[조성빈]

> 2020. 5. 2. 오후 8:24, Eli Zaretskii <eliz@gnu.org> 작성:
> 
> 
>> 
>> From: Philippe Vaucher <philippe.vaucher@gmail.com>
>> Date: Sat, 2 May 2020 12:56:41 +0200
>> Cc: tomas@tuxteam.de, Richard Stallman <rms@gnu.org>,
>> Emacs developers <emacs-devel@gnu.org>
>> 
>> I think we are mixing two concepts here. To search for a single function, where you already know the
>> keywords, yes "C-h d" works. To get a curated list of the API of a topic, not so much.
> 
> That's why I proposed to have a variant of "C-h d" that would only
> look in the arguments and in the first line of the doc string.  It
> would produce less false positives.
> 
>> I still think "C-h d alist", because it does not give me assq and assoc is not doing a good job.
> 
> they do now.
> 
>> Because alist is controversial let's take "C-h d regexp match": it does not give me string-match nor
>> match-string.
> 
> ??? It does here.
> 
>> I'm still not very satisfied about the tools you showed for listing an overview of the API to manipulate regexp,
>> or files, or processes (etc). What you are basically saying is that wanting to have this overview is overrated,
>> but for me it helps me understand the landscape of how the API works and is designed. What functions
>> would be available should I need them in the future, what parts is missing, etc.
> 
> For that, you should definitely read the manual, not just look at the
> list of APIs.  A list of the APIs will not tell enough, especially if
> you are coming to a language that has a long history, with such
> idiosyncratic names as cdr and assq.

Isn’t this the problem that the proposal is trying to address? So that people can get more info from the function names without needing to know all of the idiosyncrasies.

Re: [ELPA] New package: transient

[조성빈]

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


> 2020. 5. 2. 오후 9:03, João Távora <joaotavora@gmail.com> 작성:
> 
> 
> On Sat, May 2, 2020 at 12:40 PM Philippe Vaucher <philippe.vaucher@gmail.com> wrote:
> >>
> >> > Interesting point. I think that could work, but wouldn't it be much easier if the language itself was self-documenting?
> >>
> >> Maybe, but that entails changing the language, by definition.  And you
> >> will face resistance because languages are things people kinda grow
> >> accustomed to.  Imagine if I told you the French language should now
> >> also include all the words of Portuguese, because, you know, they're
> >> just better. Even worse with macros. It's like I told you not only you
> >> have to learn Portuguese words, but its grammar, too.
> >
> >
> > Well I propose to add new-style APIs. People can still use the old ones.
> 
> But they would have to learn to read programs in the new stuff, no?

Well learning the new stuff will be much easier & predictive if done well (and that’s the point).

> I
> never said you would be replacing words in French, just adding.
> 
> To be fair, in programming languages, one has to do that, with
> libraries.  The finer point here is that you're asking for new words
> for general purpose talk, not new words for a specific new subject, 
> like, say, nuclear frobnicators.  You'd certainly need new words for 
> that.
> 
> > But yeah, I'm coming to the conclusion that even adding a new-style
> > API is too disruptive. If it happens It'll probably live outside of
> > Emacs in MELPA.
> >
> > I'm not sure I like this simplification, but there seem to be two
> > communities of Emacs users, the "traditional" one and the "github"
> > one. Both have their perspective on how things should be, and it seems
> > that both communities have trouble understanding how the other
> > community function.
> 
> Yep. It's a simplification.  I use GitHub a lot (more than I wanted to).
> It's the only social network I use, btw, because stuff actually gets
> built there.
> 
> But indeed there is a kind of separation (though perhaps less bipolar
> than you make it appear, and more of a spectrum).  I guess I was once in
> the ruby-cool-kids-web-2.0-quick-google-ftw faction, if you understand
> what I mean, but I got to learn the old-school ways of the manual and
> Emacs -Q and now I really like them.  In 2006, I had a long
> painstakingly crafted configuration that made Emacs behave like
> Eclipse and I'm very happy to have rid myself of it (I do keep the smart
> C-a though).  Nowadays, when I find an awkward part in Emacs I ask
> myself: if people have been using this for so long, there _must_ be a
> good reason for this interface.  If I don't find an obvious answer, I
> ask here. And often, things do evolve.  But very often too, it was
> indeed a pretty good interface to start with, I just wasn't aware of it.
> Why wasn't I aware of it?  Well, indeed, Emacs could do a better job of
> communicating its superior interfaces to the world, but we're
> outnumbered against all those people that impatiently expect it to
> behave like the cool VSCode rock star screencasts, just like I once did
> about Eclipse.
> 
> João

[-- Attachment #2: Type: text/html, Size: 3879 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: 조성빈 <pcr910303@icloud.com>
> Date: Sat, 2 May 2020 21:09:11 +0900
> Cc: Philippe Vaucher <philippe.vaucher@gmail.com>, tomas@tuxteam.de,
>  rms@gnu.org, Emacs-devel@gnu.org
> 
> > For that, you should definitely read the manual, not just look at the
> > list of APIs.  A list of the APIs will not tell enough, especially if
> > you are coming to a language that has a long history, with such
> > idiosyncratic names as cdr and assq.
> 
> Isn’t this the problem that the proposal is trying to address? So that people can get more info from the function names without needing to know all of the idiosyncrasies.

Yes.  But as I wrote earlier, I think the hopes that names will solve
this problem are overrated.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 1:11 PM 조성빈 <pcr910303@icloud.com> wrote:
>
>
> 2020. 5. 2. 오후 9:03, João Távora <joaotavora@gmail.com> 작성:
>
> 
> On Sat, May 2, 2020 at 12:40 PM Philippe Vaucher <philippe.vaucher@gmail.com> wrote:
> >>
> >> > Interesting point. I think that could work, but wouldn't it be much easier if the language itself was self-documenting?
> >>
> >> Maybe, but that entails changing the language, by definition.  And you
> >> will face resistance because languages are things people kinda grow
> >> accustomed to.  Imagine if I told you the French language should now
> >> also include all the words of Portuguese, because, you know, they're
> >> just better. Even worse with macros. It's like I told you not only you
> >> have to learn Portuguese words, but its grammar, too.
> >
> >
> > Well I propose to add new-style APIs. People can still use the old ones.
>
> But they would have to learn to read programs in the new stuff, no?
>
>
> Well learning the new stuff will be much easier & predictive if done well (and that’s the point).

OK, but don't you think it's a little presumptuous to assume that?
To assume that people will find (your) new language easier make
space for it in their minds?  Languages, especially the general
purpose parts of language, are very personal and cultural. Can't
you see how this has certain echoes of proclaiming a certain
new-age culture superior to an older one? Certainly, this is
just software and not exactly world domination, but still...

João

Re: [ELPA] New package: transient

[조성빈]

> 2020. 5. 2. 오후 9:14, Eli Zaretskii <eliz@gnu.org> 작성:
> 
>> From: 조성빈 <pcr910303@icloud.com>
>> Date: Sat, 2 May 2020 21:09:11 +0900
>> Cc: Philippe Vaucher <philippe.vaucher@gmail.com>, tomas@tuxteam.de,
>> rms@gnu.org, Emacs-devel@gnu.org
>>> For that, you should definitely read the manual, not just look at the
>>> list of APIs.  A list of the APIs will not tell enough, especially if
>>> you are coming to a language that has a long history, with such
>>> idiosyncratic names as cdr and assq.
>> Isn’t this the problem that the proposal is trying to address? So that people can get more info from the function names without needing to know all of the idiosyncrasies.
> 
> Yes.  But as I wrote earlier, I think the hopes that names will solve
> this problem are overrated.

I think Philippe explained it well, but it’s useful for situations where you know the concept, used a bit, but haven’t used it enough to internalize the function names.

IMHO the function names have failed if one can’t guess simple function names without looking at the documentation at all — Everyone is saying that C-h will help, but personally the fact that one needs to open a *Help* buffer while writing elisp means that it should be improvable.

Re: [ELPA] New package: transient

[tomas]

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

On Sat, May 02, 2020 at 01:39:48PM +0200, Philippe Vaucher wrote:

[...]

> Well I propose to add new-style APIs. People can still use the old ones.

How do you guard against xkcd927 [1]?

Yes, a bit tongue-in-cheek, but the basic problem remains: discoverability
isn't "universal", and adding too many "languages" has costs of its own.

Cheers

[1] https://xkcd.com/927/
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[tomas]

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

On Sat, May 02, 2020 at 09:11:37PM +0900, 조성빈 wrote:

[...]

> Well learning the new stuff will be much easier & predictive if done well (and that’s the point).

Yes, but "well" according to whom? The ones learn better short
words (I know I do), the others long-words-with-lots-of-separators,
and so on...

Not saying one shouldn't try -- on the contrary: one should keep
trying, but I'd expect it to be a slow process, which at the same
time slowly changes direction (as tastes and needs change). So
I think one should proceed slowly: get a rough idea of the
direction to follow, agree on style guides (we do have that)
and tune those style guides (are people following them? If
not: why not?)

I'm very sceptical of taking the screwdriver to the software
before having cleared the above (have we?).

Cheers
-- tomás

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [ELPA] New package: transient

[조성빈]

> 2020. 5. 2. 오후 9:21, João Távora <joaotavora@gmail.com> 작성:
> 
> On Sat, May 2, 2020 at 1:11 PM 조성빈 <pcr910303@icloud.com> wrote:
>> 
>> 
>> 2020. 5. 2. 오후 9:03, João Távora <joaotavora@gmail.com> 작성:
>> 
>> 
>>> On Sat, May 2, 2020 at 12:40 PM Philippe Vaucher <philippe.vaucher@gmail.com> wrote:
>>>>> 
>>>>>> Interesting point. I think that could work, but wouldn't it be much easier if the language itself was self-documenting?
>>>>> 
>>>>> Maybe, but that entails changing the language, by definition.  And you
>>>>> will face resistance because languages are things people kinda grow
>>>>> accustomed to.  Imagine if I told you the French language should now
>>>>> also include all the words of Portuguese, because, you know, they're
>>>>> just better. Even worse with macros. It's like I told you not only you
>>>>> have to learn Portuguese words, but its grammar, too.
>>> 
>>> 
>>> Well I propose to add new-style APIs. People can still use the old ones.
>> 
>> But they would have to learn to read programs in the new stuff, no?
>> 
>> 
>> Well learning the new stuff will be much easier & predictive if done well (and that’s the point).
> 
> OK, but don't you think it's a little presumptuous to assume that?
> To assume that people will find (your) new language easier make
> space for it in their minds?  Languages, especially the general
> purpose parts of language, are very personal and cultural. Can't
> you see how this has certain echoes of proclaiming a certain
> new-age culture superior to an older one?

I can’t find how adding consistency is a ‘new-age culture’. I think I can understand this opinion if this thread is about some shiny new features or changing to better defaults — but why is consistent function names a ‘new-age culture’?

For an example from the ‘old culture’... (I can’t say that C has a good consistent std, but) look C’s <string.h> — all string function names start with ‘str’, memory manipulation function names start with ‘mem’ and wide variants are prefixed with ‘w’. Then comes a short abbreviation. Pretty consistent, and IMHO more predictable than elisp.

> Certainly, this is
> just software and not exactly world domination, but still...
> 
> João

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: 조성빈 <pcr910303@icloud.com>
> Cc: philippe.vaucher@gmail.com, tomas@tuxteam.de, rms@gnu.org,
>  Emacs-devel@gnu.org
> Date: Sat, 2 May 2020 21:22:26 +0900
> 
> >> Isn’t this the problem that the proposal is trying to address? So that people can get more info from the function names without needing to know all of the idiosyncrasies.
> > 
> > Yes.  But as I wrote earlier, I think the hopes that names will solve
> > this problem are overrated.
> 
> I think Philippe explained it well, but it’s useful for situations where you know the concept, used a bit, but haven’t used it enough to internalize the function names.

Philippe did explain, we just disagree about the chances of that to
solve a significant enough portion of the problem to make a
difference.  I think the existing tools will still be needed, and so
it's better to work on making those tools more accurate.

> personally the fact that one needs to open a *Help* buffer while writing elisp means that it should be improvable.

I cannot disagree more.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 1:36 PM 조성빈 <pcr910303@icloud.com> wrote:
>
>
> > 2020. 5. 2. 오후 9:21, João Távora <joaotavora@gmail.com> 작성:
> >
> > On Sat, May 2, 2020 at 1:11 PM 조성빈 <pcr910303@icloud.com> wrote:
> >>
> >>
> >> 2020. 5. 2. 오후 9:03, João Távora <joaotavora@gmail.com> 작성:
> >>
> >> 
> >>> On Sat, May 2, 2020 at 12:40 PM Philippe Vaucher <philippe.vaucher@gmail.com> wrote:
> >>>>>
> >>>>>> Interesting point. I think that could work, but wouldn't it be much easier if the language itself was self-documenting?
> >>>>>
> >>>>> Maybe, but that entails changing the language, by definition.  And you
> >>>>> will face resistance because languages are things people kinda grow
> >>>>> accustomed to.  Imagine if I told you the French language should now
> >>>>> also include all the words of Portuguese, because, you know, they're
> >>>>> just better. Even worse with macros. It's like I told you not only you
> >>>>> have to learn Portuguese words, but its grammar, too.
> >>>
> >>>
> >>> Well I propose to add new-style APIs. People can still use the old ones.
> >>
> >> But they would have to learn to read programs in the new stuff, no?
> >>
> >>
> >> Well learning the new stuff will be much easier & predictive if done well (and that’s the point).
> >
> > OK, but don't you think it's a little presumptuous to assume that?
> > To assume that people will find (your) new language easier make
> > space for it in their minds?  Languages, especially the general
> > purpose parts of language, are very personal and cultural. Can't
> > you see how this has certain echoes of proclaiming a certain
> > new-age culture superior to an older one?
>
> I can’t find how adding consistency is a ‘new-age culture’.

I suppose you speak a natural language, right? Probably
an Asian language I know nothing of. But I suppose it was something
akin to symbols/words, though. Would you like it if someone proclaims
they have a much more "consistent" set and you must learn it?

Or are you perfectly happy with what you've learned from
whomever fed you as a baby, maybe even affectionate to it, however
"inconsistent" it may be?  Do you even question consistency?

You shouldn't try change language by decree, is my point. It's a
slow process.

And who decides "consistency"? Do we even need a string library?
I don't think that's "consistent". Aren't strings sequences? Shouldn't
we be using a sequences library instead? Why not follow exclusively
Common Lisp for "consistency"? Elisp has certainly been culturally
closer to it longer than it has to Clojure.

João

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: 조성빈 <pcr910303@icloud.com>
> Date: Sat, 2 May 2020 21:36:30 +0900
> Cc: Philippe Vaucher <philippe.vaucher@gmail.com>,
>  Eli Zaretskii <eliz@gnu.org>, tomas@tuxteam.de,
>  Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
> For an example from the ‘old culture’... (I can’t say that C has a
> good consistent std, but) look C’s <string.h> — all string function
> names start with ‘str’, memory manipulation function names start
> with ‘mem’ and wide variants are prefixed with ‘w’.

Why should we only look at string.h?  That'd be akin to looking at a
single Lisp package.

That's not what was proposed.  What was proposed is to use "C-h f"
completion (or any other completion) as replacement for dedicated
documentation-search features.  If you want to compare that with a
modern standard C library, try "i mem TAB" in the glibc manual: you
will see at least 2 different families of functions not really related
to one another.  Or try "i w TAB" for an even larger variety.

> Then comes a short abbreviation. Pretty consistent, and IMHO more predictable than elisp.

ELisp is so much larger than a standard C library, though.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 2:02 PM Eli Zaretskii <eliz@gnu.org> wrote:

> > Then comes a short abbreviation. Pretty consistent, and IMHO more predictable than elisp.
> ELisp is so much larger than a standard C library, though.

And probably older.

João Távora

Re: [ELPA] New package: transient

[Stefan Monnier]

> If I may: your strategy is sub-optimal.  When looking for a function

FWIW, for me the problem is not to find the function but to remember
which permuation we chose for the one I'm thinking of.

Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
`file-name-absolute-p` or `absolute-file-name-p`, ... ?

The regexp functions mentioned elsewhere in this thread are another good
example, of course, and the lack of `looking-at` from the list they
mention is telling: the name `looking-at` prevents people from
discovering it.

Yes, we can try and improve completion, but we have a real underlying
problem of irregular naming and completion would just help us paper
over it.

We don't have to rename anything.  We can keep living with what
we have.  And we shouldn't rename the world either.  But I strongly
believe that we *should* try and rename a few things here and there
to slowly put more structure and order in our name space.
We will all benefit from it (unless we over do it, obviously).


        Stefan

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

On Sat, May 2, 2020 at 3:59 PM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > If I may: your strategy is sub-optimal.  When looking for a function
>
> FWIW, for me the problem is not to find the function but to remember
> which permuation we chose for the one I'm thinking of.
>
> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
>

Thanks, that's one point I was trying to make but you formulated it much
better than I did.

[-- Attachment #2: Type: text/html, Size: 879 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Philippe Vaucher <philippe.vaucher@gmail.com>,  tomas@tuxteam.de,
>   rms@gnu.org,  emacs-devel@gnu.org
> Date: Sat, 02 May 2020 09:59:08 -0400
> 
> > If I may: your strategy is sub-optimal.  When looking for a function
> 
> FWIW, for me the problem is not to find the function but to remember
> which permuation we chose for the one I'm thinking of.
> 
> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
> `file-name-absolute-p` or `absolute-file-name-p`, ... ?

Then "C-u C-h a WORDS..." is your friend.

> The regexp functions mentioned elsewhere in this thread are another good
> example

No, that's a different example, because a lot of regexp functions
don't have "regexp" in their names.

> Yes, we can try and improve completion, but we have a real underlying
> problem of irregular naming and completion would just help us paper
> over it.

The command "C-u C-h d regexp RET" brings up 111 matching functions.
Who will have patience looking through that list, unless the likely
candidates are near the beginning?  And this is even before we added
aliases that use the regexp- prefix.

> We don't have to rename anything.  We can keep living with what
> we have.  And we shouldn't rename the world either.  But I strongly
> believe that we *should* try and rename a few things here and there
> to slowly put more structure and order in our name space.

I don't object to this.  I'm just saying that the hope this will allow
you to quickly find that-function-you-almost-remember-the-name-of are
overly optimistic.  I'm also saying that in many use cases this will
make finding the right function harder (because the list of candidates
will become much longer).  But I personally don't care much, because I
never look for functions that way.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 2:59 PM Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>
> > If I may: your strategy is sub-optimal.  When looking for a function
>
> FWIW, for me the problem is not to find the function but to remember
> which permuation we chose for the one I'm thinking of.
>
> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
> `file-name-absolute-p` or `absolute-file-name-p`, ... ?

I feel you.  Well, flex and substring completion styles are your friends.
And M-x fido-mode even more.  In fact, this is exactly the reason I like
it so much.  You know there's "absolute" in there, just type "absolute"
, or mash "abslut".

João

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> The command "C-u C-h d regexp RET" brings up 111 matching functions.
> Who will have patience looking through that list, unless the likely
> candidates are near the beginning?  And this is even before we added
> aliases that use the regexp- prefix.


If the goal is to list all the functions related to manipulating the topic
of regexp (something like
https://docs.python.org/2/library/re.html#regular-expression-objects or
https://ruby-doc.org/core-2.7.1/Regexp.html), then the search you propose
is a poor tool.

It starts with the following list: grep-regexp-alist, gmm-regexp-concat,
project-find-regexp, shell-dumb-shell-regexp, rmail-secondary-file-regexp,
rmail-user-mail-address-regexp, tramp-file-name-regexp,
whitespace-indentation-regexp, project-or-external-find-regexp... All of
which are irrelevant to what we search.

What it should list is
https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html,
but also merged with the Match Data documentation, presented in a much more
condensed manner, etc.

Philippe

[-- Attachment #2: Type: text/html, Size: 1624 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 02.05.2020 13:39, João Távora wrote:
> If I may, it sounds like you have described a process which a (small) GNU Elpa
> package could replicate easily.  I for one would install it.  In the Common Lisp
> hyperspec pages with this kind of information are found in "the string
> dictionary",
> "the sequences dictionary".

Having to install extra packages and memorize new key bindings just for 
basic functionality like that sounds suboptimal.

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 02.05.2020 13:54, Eli Zaretskii wrote:
>>   -- Function: assoc key alist &optional testfn
>>   -- Function: rassoc value alist
>>   -- Function: assq key alist
>>   -- Function: alist-get key alist &optional default remove testfn
>>   -- Function: rassq value alist
>>   -- Function: assoc-default key alist &optional test default
>>   -- Function: copy-alist alist
>>   -- Function: assq-delete-all key alist
>>   -- Function: assoc-delete-all key alist
>>   -- Function: rassq-delete-all value alist
>>
>> That's what I would like to get out of the manual easily.
> I fail to see how will the above list be useful, if you know nothing
> about the function's name.

The workflow goes like this:

You type 'C-h f', start typing, find a function whose name looks most 
pertinent for your current purpose, then complete its name and read 
about it in detail.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 3:50 PM Dmitry Gutov <dgutov@yandex.ru> wrote:
>
> On 02.05.2020 13:39, João Távora wrote:
> > If I may, it sounds like you have described a process which a (small) GNU Elpa
> > package could replicate easily.  I for one would install it.  In the Common Lisp
> > hyperspec pages with this kind of information are found in "the string
> > dictionary",
> > "the sequences dictionary".
>
> Having to install extra packages and memorize new key bindings just for
> basic functionality like that sounds suboptimal.

Installing it is a one-time `M-x package-install` right? Anyway, I didn't want
to push it so early, but if it's indeed small and simple we could add it to
the core. And it doesn't necessarily need a keybinding, in my opinion.

João



-- 
João Távora

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 16:26:57 +0200
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, tomas@tuxteam.de, 
> 	Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
>  The command "C-u C-h d regexp RET" brings up 111 matching functions.
>  Who will have patience looking through that list, unless the likely
>  candidates are near the beginning?  And this is even before we added
>  aliases that use the regexp- prefix.
> 
> If the goal is to list all the functions related to manipulating the topic of regexp (something like
> https://docs.python.org/2/library/re.html#regular-expression-objects or
> https://ruby-doc.org/core-2.7.1/Regexp.html), then the search you propose is a poor tool.
> 
> It starts with the following list: grep-regexp-alist, gmm-regexp-concat, project-find-regexp,
> shell-dumb-shell-regexp, rmail-secondary-file-regexp, rmail-user-mail-address-regexp,
> tramp-file-name-regexp, whitespace-indentation-regexp, project-or-external-find-regexp... All of which are
> irrelevant to what we search.

Which is why I said elsewhere that without making the candidate
scoring smarter, adding aliases based on namespaces will be much less
useful, perhaps even detrimental.

> What it should list is https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html, but
> also merged with the Match Data documentation, presented in a much more condensed manner, etc.

The above are _commands_ not functions.  The equivalent would be
"C-h a regexp search RET", which does do what you want, I think.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Cc: tomas@tuxteam.de, rms@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 2 May 2020 17:56:16 +0300
> 
> On 02.05.2020 13:54, Eli Zaretskii wrote:
> >>   -- Function: assoc key alist &optional testfn
> >>   -- Function: rassoc value alist
> >>   -- Function: assq key alist
> >>   -- Function: alist-get key alist &optional default remove testfn
> >>   -- Function: rassq value alist
> >>   -- Function: assoc-default key alist &optional test default
> >>   -- Function: copy-alist alist
> >>   -- Function: assq-delete-all key alist
> >>   -- Function: assoc-delete-all key alist
> >>   -- Function: rassq-delete-all value alist
> >>
> >> That's what I would like to get out of the manual easily.
> > I fail to see how will the above list be useful, if you know nothing
> > about the function's name.
> 
> The workflow goes like this:
> 
> You type 'C-h f', start typing

I said "if you know nothing about the function's name".  How do you
"start typing" in this situation?  Typing what?

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
> > It starts with the following list: grep-regexp-alist, gmm-regexp-concat,
> project-find-regexp,
> > shell-dumb-shell-regexp, rmail-secondary-file-regexp,
> rmail-user-mail-address-regexp,
> > tramp-file-name-regexp, whitespace-indentation-regexp,
> project-or-external-find-regexp... All of which are
> > irrelevant to what we search.
>
> Which is why I said elsewhere that without making the candidate
> scoring smarter, adding aliases based on namespaces will be much less
> useful, perhaps even detrimental.
>

No, the idea is that you then search for ^regexp- and you get ONLY the
functions that start with "regexp-". I don't understand why I'm still
explaining this, if I'm missing something please tell me.



> > What it should list is
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html,
> but
> > also merged with the Match Data documentation, presented in a much more
> condensed manner, etc.
>
> The above are _commands_ not functions.  The equivalent would be
> "C-h a regexp search RET", which does do what you want, I think.
>

This again gives me a giant list where a majority of what is listed is not
what I'd like.

[-- Attachment #2: Type: text/html, Size: 1760 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 02.05.2020 18:37, Eli Zaretskii wrote:
>> Cc:tomas@tuxteam.de,rms@gnu.org,emacs-devel@gnu.org
>> From: Dmitry Gutov<dgutov@yandex.ru>
>> Date: Sat, 2 May 2020 17:56:16 +0300
>>
>> On 02.05.2020 13:54, Eli Zaretskii wrote:
>>>>    -- Function: assoc key alist &optional testfn
>>>>    -- Function: rassoc value alist
>>>>    -- Function: assq key alist
>>>>    -- Function: alist-get key alist &optional default remove testfn
>>>>    -- Function: rassq value alist
>>>>    -- Function: assoc-default key alist &optional test default
>>>>    -- Function: copy-alist alist
>>>>    -- Function: assq-delete-all key alist
>>>>    -- Function: assoc-delete-all key alist
>>>>    -- Function: rassq-delete-all value alist
>>>>
>>>> That's what I would like to get out of the manual easily.
>>> I fail to see how will the above list be useful, if you know nothing
>>> about the function's name.
>> The workflow goes like this:
>>
>> You type 'C-h f', start typing
> I said "if you know nothing about the function's name".  How do you
> "start typing" in this situation?  Typing what?

The more frequent case is when you know *something*.

"Know nothing" is a strawman. Or it presupposes that function names are 
frequently such that it's impossible to guess. We do have a few of 
those, but they are a historical oddity, and we shouldn't add more.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 17:43:34 +0200
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, tomas@tuxteam.de, 
> 	Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
>  > It starts with the following list: grep-regexp-alist, gmm-regexp-concat, project-find-regexp,
>  > shell-dumb-shell-regexp, rmail-secondary-file-regexp, rmail-user-mail-address-regexp,
>  > tramp-file-name-regexp, whitespace-indentation-regexp, project-or-external-find-regexp... All of which
>  are
>  > irrelevant to what we search.
> 
>  Which is why I said elsewhere that without making the candidate
>  scoring smarter, adding aliases based on namespaces will be much less
>  useful, perhaps even detrimental.
> 
> No, the idea is that you then search for ^regexp- and you get ONLY the functions that start with "regexp-". I
> don't understand why I'm still explaining this, if I'm missing something please tell me.

You are missing the fact that it's impossible to make all functions
related to regexps begin with "regexp-", because some of them are also
related to lists or strings or buffers or email or projects.  Or are
you suggesting to have dozens of different aliases for each function,
one each for every class to which it could possibly belong?

>  > What it should list is
>  https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html, but
>  > also merged with the Match Data documentation, presented in a much more condensed manner,
>  etc.
> 
>  The above are _commands_ not functions.  The equivalent would be
>  "C-h a regexp search RET", which does do what you want, I think.
> 
> This again gives me a giant list where a majority of what is listed is not what I'd like. 

"Giant"?  I see 11 hits (in "emacs -Q").

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Cc: philippe.vaucher@gmail.com, tomas@tuxteam.de, rms@gnu.org,
>  emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 2 May 2020 18:51:34 +0300
> 
> >> You type 'C-h f', start typing
> > I said "if you know nothing about the function's name".  How do you
> > "start typing" in this situation?  Typing what?
> 
> The more frequent case is when you know *something*.

"Something" that appears in the name, or "something" that is related
to what the function does?  If the latter, then you are much better
off with index-search in Info.  And since knowing something about the
functions domain is a superset of knowing something about its name,
the Info index-search is a more efficient tool in these cases.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

> > No, the idea is that you then search for ^regexp- and you get ONLY the
> functions that start with "regexp-". I
> > don't understand why I'm still explaining this, if I'm missing something
> please tell me.
>
> You are missing the fact that it's impossible to make all functions
> related to regexps begin with "regexp-", because some of them are also
> related to lists or strings or buffers or email or projects.  Or are
> you suggesting to have dozens of different aliases for each function,
> one each for every class to which it could possibly belong?
>

How big is this "some of them" you are talking about? Are they really about
regexp, or another topic? And are you implying that because we cannot do
all of them, we should do any of them?



> >  > What it should list is
> >
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html,
> but
> >  > also merged with the Match Data documentation, presented in a much
> more condensed manner,
> >  etc.
> >
> >  The above are _commands_ not functions.  The equivalent would be
> >  "C-h a regexp search RET", which does do what you want, I think.
> >
> > This again gives me a giant list where a majority of what is listed is
> not what I'd like.
>
> "Giant"?  I see 11 hits (in "emacs -Q").
>

In "Emacs -Q" you are correct. Without "-Q" the list is here
https://www.ideone.com/35kbNi. On that list only line 116-127 are relevant
to what I search.

Philippe

[-- Attachment #2: Type: text/html, Size: 2246 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <philippe.vaucher@gmail.com>
> Date: Sat, 2 May 2020 18:12:37 +0200
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, tomas@tuxteam.de, 
> 	Richard Stallman <rms@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
>  You are missing the fact that it's impossible to make all functions
>  related to regexps begin with "regexp-", because some of them are also
>  related to lists or strings or buffers or email or projects.  Or are
>  you suggesting to have dozens of different aliases for each function,
>  one each for every class to which it could possibly belong?
> 
> How big is this "some of them" you are talking about? Are they really about regexp, or another topic?

"C-u C-h a regexp RET" and see for yourself.

> And are you implying that because we cannot do all of them, we should do any of them?

No, I'm not implying that.

>  >  The above are _commands_ not functions.  The equivalent would be
>  >  "C-h a regexp search RET", which does do what you want, I think.
>  > 
>  > This again gives me a giant list where a majority of what is listed is not what I'd like. 
> 
>  "Giant"?  I see 11 hits (in "emacs -Q").
> 
> In "Emacs -Q" you are correct. Without "-Q" the list is here https://www.ideone.com/35kbNi. On that list only
> line 116-127 are relevant to what I search.

You didn't type "C-h a", because that only shows commands.

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>  You are missing the fact that it's impossible to make all functions
> >  related to regexps begin with "regexp-", because some of them are also
> >  related to lists or strings or buffers or email or projects.  Or are
> >  you suggesting to have dozens of different aliases for each function,
> >  one each for every class to which it could possibly belong?
> >
> > How big is this "some of them" you are talking about? Are they really
> about regexp, or another topic?
>
> "C-u C-h a regexp RET" and see for yourself.
>

I see very few candidates where it's unclear... and almost all the results
is already properly namespaced (under dired when it concern dired, etc).

Remember the proposal is to unify what is the building blocks of regexps
under the regexp- namespace. NOT to put everything that contains "regexp"
under that namespace. That means how to create regexps, how to apply them
to strings, how to get the match results. There might be things where it's
hard to decide which is the main topic but that is more related to generic
functions, which can remain generic for now until we figure it out.

The proposal is to start where it's obvious, not to sort it all out for all
cases.

>  >  The above are _commands_ not functions.  The equivalent would be
> >  >  "C-h a regexp search RET", which does do what you want, I think.
> >  >
> >  > This again gives me a giant list where a majority of what is listed
> is not what I'd like.
> >
> >  "Giant"?  I see 11 hits (in "emacs -Q").
> >
> > In "Emacs -Q" you are correct. Without "-Q" the list is here
> https://www.ideone.com/35kbNi. On that list only
> > line 116-127 are relevant to what I search.
>
> You didn't type "C-h a", because that only shows commands.
>

Okay my bad, on my setup that binding runs `counsel-apropos` and not
`apropos-command`. This is why you thought the list was reasonable and I
thought it wasn't. Sorry.

Philippe

[-- Attachment #2: Type: text/html, Size: 2714 bytes --]

Re: [ELPA] New package: transient

[Stefan Monnier]

>> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
>> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
> Then "C-u C-h a WORDS..." is your friend.

Nope, way too slow.  I shouldn't have to do anything more than `str-mul TAB`.
The only reason I have to do more is because of the accidental naming inconsistency.

We can't solve all problems by careful naming.  But that doesn't mean we
shouldn't improve our naming when there's a clearly better choice.

>> The regexp functions mentioned elsewhere in this thread are another good
>> example
> No, that's a different example, because a lot of regexp functions
> don't have "regexp" in their names.

It's a different example, yes, but I think it's a very good one.
I use those functions often enough to remember their names, luckily, but
for the more occasional user it's not nearly as simple.

>> Yes, we can try and improve completion, but we have a real underlying
>> problem of irregular naming and completion would just help us paper
>> over it.
> The command "C-u C-h d regexp RET" brings up 111 matching functions.
> Who will have patience looking through that list, unless the likely
> candidates are near the beginning?

IIUC that means you agree with my argument?

> I don't object to this.  I'm just saying that the hope this will allow
> you to quickly find that-function-you-almost-remember-the-name-of are
> overly optimistic.

We impose a prefix convention on the rest of the Elisp world, and while
some authors don't like it, I find that it is not just useful much more
generally than to avoid conflicts, so we should try and use it for
Emacs's core as well.

It's not a new opinion, BTW: I started doing that back in Emacs-21 with
the newcomment.el package which tried to stick to the "comment-" prefix
even for things which previously used a different name.


        Stefan

RE: [ELPA] New package: transient

[Drew Adams]

> > I think there is no need to rigidly put the crucial word 'alist'
> > at the start of the name.  Just having 'alist' in the function name
> > makes it easy enough to find that function.
> 
> Not if you type "alist- TAB" and expect to see
> that function in the list of completion candidates.

Not if you use only prefix completion.
But yes, if you use substring completion.
Or regexp or fuzzy completion.

RE: [ELPA] New package: transient

[Drew Adams]

[Please consider using plain-text mail for Emacs
mailing lists.  Thx.]

> With alist, searching for `.*alist.*`  is not
> so bad, but with `file-name` the problem shows
> more clearly: you have a lot of results that
> you'd like to ignore (functions from tramp, etc).

The question is how to tell the program
(Emacs, here) which results you'd like to
ignore.

You can try using a fancy search pattern.
You can try to use a fancy matching method.
Or you can try to _combine_ simple matches
(patterns and methods).

But with all of that it's hard to filter
out just what _you know_ you don't want.

You can use matching itself to exclude an
existing set of matches.  But that has to
be a separate operation - after matching:
Toss these results from matching.

That was the subject of a previous message
of mine, where I pointed out the value of
having a key that removes a set of matches.

You _cannot_ express non-matching with a
regexp, for example.  The approach to take
is to instead explicitly get matches for
what you do NOT want, and then subtract
those from a larger set of matches that
includes what you want.

That's what we do in Lisp code.  And it's
what's most helpful interactively, as well.

https://www.emacswiki.org/emacs/Icicles_-_Nutshell_View#ChippingAway

RE: [ELPA] New package: transient

[Drew Adams]

> When looking for a function
> whose name you don't know, the first place to look is in the ELisp
> manual.  Thus, for finding functions that deal with alists, the first
> thing to try is "i alist RET" in the ELisp manual.  Here "alist" is
> not a part of a function's name, it's a topic which you are looking
> for.  That is much more efficient than the sequence you described
> above, because we take special care of having meaningful topics in the
> indices of the manual, precisely to help in such situations.  (And my
> advice is to always have the ELisp manual shown in some frame on your
> display, so that you don't even need to type "C-h i" etc. to get to
> it.)

I agree with Eli about this.  ` i' in a manual is
your friend.

However, that's usable only for functions etc. in
the vanilla code distributed with Emacs.  Maybe
that's all Philippe is interested in this case;
maybe not.

If a user wants a function that acts on or returns
an alist, and wants to include functions that are
not part of vanilla Emacs, then the interactive
help, not the manuals, are the answer.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: philippe.vaucher@gmail.com,  tomas@tuxteam.de,  rms@gnu.org,
>   emacs-devel@gnu.org
> Date: Sat, 02 May 2020 12:48:33 -0400
> 
> >> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
> >> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
> > Then "C-u C-h a WORDS..." is your friend.
> 
> Nope, way too slow.

Is that the only problem? then let's speed it up, and Bob's our uncle.

> I shouldn't have to do anything more than `str-mul TAB`.

If you remembered the function's name, yes.  But that's not the use
case we are discussing here.

> >> Yes, we can try and improve completion, but we have a real underlying
> >> problem of irregular naming and completion would just help us paper
> >> over it.
> > The command "C-u C-h d regexp RET" brings up 111 matching functions.
> > Who will have patience looking through that list, unless the likely
> > candidates are near the beginning?
> 
> IIUC that means you agree with my argument?

Of course not!  I'm saying that "regular naming" will increase the
length of the candidate list.

> > I don't object to this.  I'm just saying that the hope this will allow
> > you to quickly find that-function-you-almost-remember-the-name-of are
> > overly optimistic.
> 
> We impose a prefix convention on the rest of the Elisp world, and while
> some authors don't like it, I find that it is not just useful much more
> generally than to avoid conflicts, so we should try and use it for
> Emacs's core as well.

The prefix convention we impose has almost nothing to do with the
issue at hand, because the package's name in many (most?) cases says
nothing about its domain of application.  E.g., take message.el or
tmm.el or windmove.el or tempo.el or xdg.el, to name just a few random
examples.

> It's not a new opinion, BTW: I started doing that back in Emacs-21 with
> the newcomment.el package which tried to stick to the "comment-" prefix
> even for things which previously used a different name.

Beginner's luck.  Occasionally, this could just happen to work, when
the package's name happens to say something about its purpose.  But
mostly it doesn't, as packages like the one whose name is in the
Subject clearly demonstrate.

RE: [ELPA] New package: transient

[Drew Adams]

> My original use case is: I want to copy an association list,
> I know the function will probably have "copy" in its name
> and "alist",

Maybe, maybe not.  Yep, there's a function named
`copy-alist'.  A win.

But in general the function you want might have
"copy" and something more general than "alist"
in its name.

What's an alist?  It's a list.  What's a (true)
list?  It's a sequence.

`copy-sequence' (aka `copy-seq') also copies an
alist.

So yeah, it's sometimes about things, not just
their names.

If `copy-alist' didn't exist, then no reasonable
naming scheme would have gotten you there.
You'd have to have some understanding that an
alist is a list is a sequence.  And _then_, sure,
good naming can help.

And in this case, just `C-h f copy TAB' gives you
a list of 41 function names, and it's pretty easy
to see find `copy-alist', `copy-sequence', and
`copy-seq'.

(If it weren't easy, it would at least be easy to
match others and remove those other matches,
assuming you have a way to do that.)

RE: [ELPA] New package: transient

[Drew Adams]

> My earnest advice for those developers is to try the features I
> mentioned, they might find them useful in situations similar to the
> one you described, and they might then decide to use them more than
> what they do today.

+1.  The most important, most useful thing
to learn in Emacs is how to _ask Emacs_.

That should be the main emphasis of any
intro, tutorial, etc. to using Emacs.  It's
the key to unlocking the door - the key to
learning Emacs any way that works for _you_.

RE: [ELPA] New package: transient

[Drew Adams]

> I think demanding namespacing for discoverability
> is mixing up two not entirely orthogonal but also
> not entirely dependent things.

This.

My guess is that it's from a particular habit.
We all have our ingrained ways of working.

Emacs and Lisp are a bit different from what
many programmers are used to.  That's NOT
something new.  Back in the day, newbies came
to Emacs and Lisp from Fortran, C, Basic,
Pascal, etc.  Those are _at least_ as alien
from Lisp as are Java, Python, etc.  (Fortran
didn't even have recursion!  Trying to grok a
Lisp definition of `append' was mind-blowing.)

RE: [ELPA] New package: transient

[Drew Adams]

> the French language should now also include all
> the words of Portuguese, because, you know,
> they're just better.

Yes!  Please file an enhancement request for this
to the Academie Francaise.

Re: [ELPA] New package: transient

[조성빈]

Eli Zaretskii <eliz@gnu.org> 작성:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Cc: philippe.vaucher@gmail.com,  tomas@tuxteam.de,  rms@gnu.org,
>>   emacs-devel@gnu.org
>> Date: Sat, 02 May 2020 12:48:33 -0400
>>
>>>> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
>>>> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
>>> Then "C-u C-h a WORDS..." is your friend.
>>
>> Nope, way too slow.
>
> Is that the only problem? then let's speed it up, and Bob's our uncle.

My understanding is that slow here means that opening a new *Apropos*
buffer is an small, but additional mental burden when writing code, and
it slows down writing code.

>> I shouldn't have to do anything more than `str-mul TAB`.
>
> If you remembered the function's name, yes.  But that's not the use
> case we are discussing here.

I think there are a lot of use cases here buried in the flood of mail
- but everyone has a different use case where the prefix-convention will
work better. We’re not trying to say that Emacs’s documentation system is
not useful.

>>>> Yes, we can try and improve completion, but we have a real underlying
>>>> problem of irregular naming and completion would just help us paper
>>>> over it.
>>> The command "C-u C-h d regexp RET" brings up 111 matching functions.
>>> Who will have patience looking through that list, unless the likely
>>> candidates are near the beginning?
>>
>> IIUC that means you agree with my argument?
>
> Of course not!  I'm saying that "regular naming" will increase the
> length of the candidate list.

The regular naming scheme will mean that we can only search functions that
start with regexp - since the searcher doesn’t need grep-regexp-alist or
gmm-regexp-concat when trying to get regexp APIs.

>>> I don't object to this.  I'm just saying that the hope this will allow
>>> you to quickly find that-function-you-almost-remember-the-name-of are
>>> overly optimistic.
>>
>> We impose a prefix convention on the rest of the Elisp world, and while
>> some authors don't like it, I find that it is not just useful much more
>> generally than to avoid conflicts, so we should try and use it for
>> Emacs's core as well.
>
> The prefix convention we impose has almost nothing to do with the
> issue at hand, because the package's name in many (most?) cases says
> nothing about its domain of application.  E.g., take message.el or
> tmm.el or windmove.el or tempo.el or xdg.el, to name just a few random
> examples.
>
>> It's not a new opinion, BTW: I started doing that back in Emacs-21 with
>> the newcomment.el package which tried to stick to the "comment-" prefix
>> even for things which previously used a different name.
>
> Beginner's luck.  Occasionally, this could just happen to work, when
> the package's name happens to say something about its purpose.  But
> mostly it doesn't, as packages like the one whose name is in the
> Subject clearly demonstrate.

RE: [ELPA] New package: transient

[Drew Adams]

> If the goal is to list all the functions related to
> manipulating the topic of regexp (something like ...
> or ...

Those lists do not show you all such functions,
do they?  They presumably show you only the
functions that are part of the language definition.

In Lisp, there's little boundary between what the
language provides out of the box and what it
provides dynamically, in your session.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: 조성빈 <pcr910303@icloud.com>
> Date: Sun, 3 May 2020 03:10:50 +0900
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>  tomas@tuxteam.de,
>  rms@gnu.org,
>  emacs-devel@gnu.org
> 
> >>> Then "C-u C-h a WORDS..." is your friend.
> >>
> >> Nope, way too slow.
> >
> > Is that the only problem? then let's speed it up, and Bob's our uncle.
> 
> My understanding is that slow here means that opening a new *Apropos*
> buffer is an small, but additional mental burden when writing code, and
> it slows down writing code.

How is that different from having *Completions* pop up instead?

And how is looking up the function you need a "burden", when any
modern IDE provides some way of showing the possible candidates for
what you want to do next?  I say it isn't a burden, it's an integral
part of writing code nowadays.

> > Of course not!  I'm saying that "regular naming" will increase the
> > length of the candidate list.
> 
> The regular naming scheme will mean that we can only search functions that
> start with regexp - since the searcher doesn’t need grep-regexp-alist or
> gmm-regexp-concat when trying to get regexp APIs.

Do they need rx, as just one example?

Re: [ELPA] New package: transient

[Yuan Fu]

Maybe we should open a new thread and discuss renaming there, and leave this thread for discussing adding transient to ELPA.

Yuan

Re: [ELPA] New package: transient

[조성빈]

Eli Zaretskii <eliz@gnu.org> 작성:

>> From: 조성빈 <pcr910303@icloud.com>
>> Date: Sun, 3 May 2020 03:10:50 +0900
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>>  tomas@tuxteam.de,
>>  rms@gnu.org,
>>  emacs-devel@gnu.org
>>
>>>>> Then "C-u C-h a WORDS..." is your friend.
>>>>
>>>> Nope, way too slow.
>>>
>>> Is that the only problem? then let's speed it up, and Bob's our uncle.
>>
>> My understanding is that slow here means that opening a new *Apropos*
>> buffer is an small, but additional mental burden when writing code, and
>> it slows down writing code.
>
> How is that different from having *Completions* pop up instead?

Which… is why a lot of people don’t use *Completion* and use company-mode
(or some other methods).

> And how is looking up the function you need a "burden", when any
> modern IDE provides some way of showing the possible candidates for
> what you want to do next?

Modern IDEs provide the candidates without needing to do any action.
It’s very different from having to explicitly look up.
(And that’s where the burden comes.)

> I say it isn't a burden, it's an integral
> part of writing code nowadays.
>
>>> Of course not!  I'm saying that "regular naming" will increase the
>>> length of the candidate list.
>>
>> The regular naming scheme will mean that we can only search functions that
>> start with regexp - since the searcher doesn’t need grep-regexp-alist or
>> gmm-regexp-concat when trying to get regexp APIs.
>
> Do they need rx, as just one example?

I think that’s a different question.
(FWIW, I consider that rx shouldn’t appear.)
Whether or not the searcher wants to know about rx or not,
it’s probably true that one doesn’t want gmm-regexp-concat.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: 조성빈 <pcr910303@icloud.com>
> Date: Sun, 3 May 2020 03:37:31 +0900
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>  tomas@tuxteam.de,
>  rms@gnu.org,
>  emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> 작성:
> 
> >> My understanding is that slow here means that opening a new *Apropos*
> >> buffer is an small, but additional mental burden when writing code, and
> >> it slows down writing code.
> >
> > How is that different from having *Completions* pop up instead?
> 
> Which… is why a lot of people don’t use *Completion* and use company-mode

Which does the same, just in a menu.  How's that different?

> > And how is looking up the function you need a "burden", when any
> > modern IDE provides some way of showing the possible candidates for
> > what you want to do next?
> 
> Modern IDEs provide the candidates without needing to do any action.

How's that relevant to the issue at hand?  It's a tangent.

> It’s very different from having to explicitly look up.

No, it isn't.  "Look up" means look through the list of candidates,
applying some logic towards the decision which candidate to choose.

> >> The regular naming scheme will mean that we can only search functions that
> >> start with regexp - since the searcher doesn’t need grep-regexp-alist or
> >> gmm-regexp-concat when trying to get regexp APIs.
> >
> > Do they need rx, as just one example?
> 
> I think that’s a different question.
> (FWIW, I consider that rx shouldn’t appear.)

Let's see how the re- renaming thread evolves, I'm not sure everyone
will agree.

> Whether or not the searcher wants to know about rx or not,
> it’s probably true that one doesn’t want gmm-regexp-concat.

Why not?  Sounds like a very useful function for someone who works
with regular expressions.

RE: [ELPA] New package: transient

[Drew Adams]

> >> is it `multibyte-string-p` or `string-multibyte-p`,
> >> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
> > Then "C-u C-h a WORDS..." is your friend.
> 
> Nope, way too slow.  I shouldn't have to do anything
> more than `str-mul TAB`.

In Icicles I type `C-h f str S-SPC mul',
and I get these candidates (all from vanilla Emacs):

 article-strip-multiple-blank-lines  (command)
 gnus-article-strip-multiple-blank-lines  (command) 
 gnus-multi-decode-encoded-word-string
 multibyte-string-p 
 read-multilingual-string
 string-as-multibyte 
 string-make-multibyte
 string-to-multibyte

And `C-h f file S-SPC abs' gives these (plus some
Icicles and Dired+ functions):

 file-name-absolute-p
 files--name-absolute-system-p 
 tramp-use-absolute-autoload-file-names

`S-SPC' lets you combine multiple patterns, with
no regard to the order of their matches in a
candidate.  Matching patterns `file' and `abs'
doesn't care which match comes first in the
function name.

(If you don't like to use `S-SPC' (and so be able
to match candidates that have SPC chars in them)
then just change that key to `SPC', comma, or
whatever.)

> BTW: I started doing that back in Emacs-21 with
> the newcomment.el package which tried to stick
> to the "comment-" prefix even for things which
> previously used a different name.

Oh, like `comment-make-bol-ws', `comment-quote-re',
`comment-string-strip', `comment-string-reverse',
and `comment-with-narrowing', which seem to have
nothing particular to do with comments, except that
they happen to be used to implement some code that
handles comments?

A package prefix is one thing.  A prefix that
advertises the type of thing that a function works
with is another thing.  Just what is the prefix
`comment-', here?

Re: [ELPA] New package: transient

[조성빈]

> 2020. 5. 3. 오전 3:46, Eli Zaretskii <eliz@gnu.org> 작성:
> 
> 
>> From: 조성빈 <pcr910303@icloud.com>
>> Date: Sun, 3 May 2020 03:37:31 +0900
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>> tomas@tuxteam.de,
>> rms@gnu.org,
>> emacs-devel@gnu.org
>> Eli Zaretskii <eliz@gnu.org> 작성:
>>>> My understanding is that slow here means that opening a new *Apropos*
>>>> buffer is an small, but additional mental burden when writing code, and
>>>> it slows down writing code.
>>> How is that different from having *Completions* pop up instead?
>> Which… is why a lot of people don’t use *Completion* and use company-mode
> 
> Which does the same, just in a menu.  How's that different?
> 
>>> And how is looking up the function you need a "burden", when any
>>> modern IDE provides some way of showing the possible candidates for
>>> what you want to do next?
>> Modern IDEs provide the candidates without needing to do any action.
> 
> How's that relevant to the issue at hand?  It's a tangent.
> 
>> It’s very different from having to explicitly look up.
> 
> No, it isn't.  "Look up" means look through the list of candidates,
> applying some logic towards the decision which candidate to choose.

I’m assuming you aren’t using auto completion here — sorry if it’s not true.

Looking up with C-h means one has to explicitly trigger a search with a search term. In contrast, with auto completion it’s basically searching with the latest token one is typing. Which means it has much less burden.

One of the many reasons I prefer the prefix scheme is because it works with completion well — which is probably also related to discoverability.

>>>> The regular naming scheme will mean that we can only search functions that
>>>> start with regexp - since the searcher doesn’t need grep-regexp-alist or
>>>> gmm-regexp-concat when trying to get regexp APIs.
>>> Do they need rx, as just one example?
>> I think that’s a different question.
>> (FWIW, I consider that rx shouldn’t appear.)
> 
> Let's see how the re- renaming thread evolves, I'm not sure everyone
> will agree.

Yes, that kind of bike shedding is the reason why this mailing list exists, right?
It’s great to me that there’s at least discussion about this here.

>> Whether or not the searcher wants to know about rx or not,
>> it’s probably true that one doesn’t want gmm-regexp-concat.
> 
> Why not?  Sounds like a very useful function for someone who works
> with regular expressions.

Oops, looks like I should really sleep. I was meaning grep-regexp-alist.

Re: [ELPA] New package: transient

[조성빈]

> 2020. 5. 3. 오전 3:58, Drew Adams <drew.adams@oracle.com> 작성:
> 
> 
>> 
>>>> is it `multibyte-string-p` or `string-multibyte-p`,
>>>> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
>>> Then "C-u C-h a WORDS..." is your friend.
>> 
>> Nope, way too slow.  I shouldn't have to do anything
>> more than `str-mul TAB`.
> 
> In Icicles I type `C-h f str S-SPC mul',
> and I get these candidates (all from vanilla Emacs):
> 
> article-strip-multiple-blank-lines  (command)
> gnus-article-strip-multiple-blank-lines  (command) 
> gnus-multi-decode-encoded-word-string
> multibyte-string-p 
> read-multilingual-string
> string-as-multibyte 
> string-make-multibyte
> string-to-multibyte

Yes, and the fact that there are functions from gnus is a problem — the user only wanted a function that handles strings, but there is no such way to encode that in search with the current naming scheme.

> And `C-h f file S-SPC abs' gives these (plus some
> Icicles and Dired+ functions):
> 
> file-name-absolute-p
> files--name-absolute-system-p 
> tramp-use-absolute-autoload-file-names
> 
> `S-SPC' lets you combine multiple patterns, with
> no regard to the order of their matches in a
> candidate.  Matching patterns `file' and `abs'
> doesn't care which match comes first in the
> function name.
> 
> (If you don't like to use `S-SPC' (and so be able
> to match candidates that have SPC chars in them)
> then just change that key to `SPC', comma, or
> whatever.)
> 
>> BTW: I started doing that back in Emacs-21 with
>> the newcomment.el package which tried to stick
>> to the "comment-" prefix even for things which
>> previously used a different name.
> 
> Oh, like `comment-make-bol-ws', `comment-quote-re',
> `comment-string-strip', `comment-string-reverse',
> and `comment-with-narrowing', which seem to have
> nothing particular to do with comments, except that
> they happen to be used to implement some code that
> handles comments?
> 
> A package prefix is one thing.  A prefix that
> advertises the type of thing that a function works
> with is another thing.  Just what is the prefix
> `comment-', here?
> 

RE: [ELPA] New package: transient

[Drew Adams]

> Modern IDEs provide the candidates without needing to do any action.
> It’s very different from having to explicitly look up.
> (And that’s where the burden comes.)

A good UI offers both possibilities: show
completions automatically or show them on
demand (e.g. hitting `TAB').

One consideration is how many completion
candidates there are, how many of them you
want to see, and why you want to see them.

UIs such as Ido, for example, show only a few
candidates, even when there may be many.  And
those UIs typically do kick in automatically.

But what if you want to see lots of candidates?
(There are several reasons you might want to.)
In that case, do you want a huge popup that
shows them?

Users should be in control.  They should at
least have a user option that controls this
in general.  Additionally it's good if they
can control this on the fly (how many max,
whether to show automatically, etc.)
___

(FWIW, Icicles offers such user control.)

RE: [ELPA] New package: transient

[Drew Adams]

> >>>> is it `multibyte-string-p` or `string-multibyte-p`,
> >>>> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
> >>> Then "C-u C-h a WORDS..." is your friend.
> >>
> >> Nope, way too slow.  I shouldn't have to do anything
> >> more than `str-mul TAB`.
> >
> > In Icicles I type `C-h f str S-SPC mul',
> > and I get these candidates (all from vanilla Emacs):
> >
> > article-strip-multiple-blank-lines  (command)
> > gnus-article-strip-multiple-blank-lines  (command)
> > gnus-multi-decode-encoded-word-string
> > multibyte-string-p
> > read-multilingual-string
> > string-as-multibyte
> > string-make-multibyte
> > string-to-multibyte
> 
> Yes, and the fact that there are functions from gnus is a problem — the
> user only wanted a function that handles strings, but there is no such
> way to encode that in search with the current naming scheme.

I was using Stefan's example of `str' and `mul'.

Any way you look at it, those alone are not enough
to exclude the gnus etc. stuff.

But `str' and `tiby' give you:

 multibyte-string-p
 string-as-multibyte
 string-make-multibyte
 string-to-multibyte

Re: [ELPA] New package: transient

[Stefan Monnier]

>> >> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
>> >> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
>> > Then "C-u C-h a WORDS..." is your friend.
>> Nope, way too slow.
> Is that the only problem? then let's speed it up, and Bob's our uncle.

When I say "slow" I measure the time in number of hand movements.
I'm in the middle of writing code, I might have already written `str`
even and now I'd have to do `C-u C-h a str mul RET` and that will only
display the answer, I still have to find it in the list and then arrange
for it to make its way to my buffer.

Compared to `-mul TAB`, I can't see any way the `C-h` route could be
even remotely competitive.

>> I shouldn't have to do anything more than `str-mul TAB`.
> If you remembered the function's name, yes.  But that's not the use
> case we are discussing here.

I remember it's a string manipulating function and it has "multibyte"
in its name, so `str-mul` *should* find it (along with a few other
candidates, probably), even if I can't remember the whole name.

>> >> Yes, we can try and improve completion, but we have a real underlying
>> >> problem of irregular naming and completion would just help us paper
>> >> over it.
>> > The command "C-u C-h d regexp RET" brings up 111 matching functions.
>> > Who will have patience looking through that list, unless the likely
>> > candidates are near the beginning?
>> IIUC that means you agree with my argument?
> Of course not!  I'm saying that "regular naming" will increase the
> length of the candidate list.

No, because it lets you use a more targeted (non-substring) matching, so
you'll have much fewer matches.

Having a bit more or a bit less than 111 matches makes no difference: as
you say "who will have patience looking through that list"?  You need to
narrow down that list and the only way to do it (short of removing
existing functions) is to use a less permissive matching.

> The prefix convention we impose has almost nothing to do with the
> issue at hand, because the package's name in many (most?) cases says
> nothing about its domain of application.  E.g., take message.el or
> tmm.el or windmove.el or tempo.el or xdg.el, to name just a few random
> examples.

That's only unhelpful in the case where you don't know the relevant
prefix name.  In such a situation, you definitely need to resort to some
kind of manual to find your way to relevant library.

A regular/structured naming system doesn't help for that, but it helps
afterwards: once you know under which prefix things should be found,
then you can find the relevant function more easily.

>> It's not a new opinion, BTW: I started doing that back in Emacs-21 with
>> the newcomment.el package which tried to stick to the "comment-" prefix
>> even for things which previously used a different name.
> Beginner's luck.  Occasionally, this could just happen to work, when
> the package's name happens to say something about its purpose.  But
> mostly it doesn't, as packages like the one whose name is in the
> Subject clearly demonstrate.

No, the actual name is irrelevant to my argument.  What is relevant is
that the *same* name is used, so the functions are grouped together in
the namespace.


        Stefan "who finds this discussion enlightening, because he took
                it for granted that everyone knows that such structuring
                is *obviously* good (tho not necessarily always best)."

Re: [ELPA] New package: transient

[Stefan Monnier]

> Maybe we should open a new thread and discuss renaming there, and leave this
> thread for discussing adding transient to ELPA.

AFAIK "adding transient to ELPA" is not under discussion any more
(I think it's in process and doesn't require any particular discussion).


        Stefan

Re: [ELPA] New package: transient

[Stefan Monnier]

>> BTW: I started doing that back in Emacs-21 with
>> the newcomment.el package which tried to stick
>> to the "comment-" prefix even for things which
>> previously used a different name.
> Oh, like `comment-make-bol-ws', `comment-quote-re',
> `comment-string-strip', `comment-string-reverse',
> and `comment-with-narrowing', which seem to have
> nothing particular to do with comments, except that
> they happen to be used to implement some code that
> handles comments?

No, these should have "--" in their name, but that convention wasn't
used back then, sadly.  I was thinking of things like
`comment-indent-new-line`, `comment-kill`, `comment-set-column`,
`comment-indent`.


        Stefan

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 9:40 PM Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>         Stefan "who finds this discussion enlightening, because he took
>                 it for granted that everyone knows that such structuring
>                 is *obviously* good (tho not necessarily always best)."

Yes, it's been a fine bikeshedding Saturday. One final shedding
of the bike from me. As you may know, in Common Lisp, a close
cousin to Elisp (though I think not _directly_ related), there are
packages. The main CL package has all the idiosyncrasies people
complain of here, but no-one would dare suggest renaming them,
because they're burned in the standard, and everyone eventually
learns it: it's a non-issue. But, because of the package system,
some people do write so-called  "modern" libraries which live tidily
in their own package and can be used with libraries that would
otherwise clash in namespace. So depending on which packages you
are using, CONCAT might be a particularly devious feline.
There are utilities packages for every taste, Alexandria, Rutils,
Arnesi, etc, etc.  Recently there's even a "modern string library",
probably like s.el but, crucially, it doesn't use a one-char package
nickname. So coexistence of modern and the old-school really
works in CL. But even if you load a package that brings in packages
packages you don't like, they will never interfere with the symbols
available in the package where you are writing your code. Which
is brilliant and exactly what is missing in Elisp, to fix this discussion.
Not to mention the mammoth feeling of bliss that you will feel when
you realize you _don't_ have to prefix every symbol with the same
word over and over and over.

...and over and over and over...
João

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

>
>         Stefan "who finds this discussion enlightening, because he took
>                 it for granted that everyone knows that such structuring
>                 is *obviously* good (tho not necessarily always best)."
>

This is also what I take out of this. It makes me curious about the topics
where it's in the other direction (where I don't "get" something a lot of
people take for granted).

[-- Attachment #2: Type: text/html, Size: 666 bytes --]

RE: [ELPA] New package: transient

[Drew Adams]

> As you may know, in Common Lisp, a close
> cousin to Elisp (though I think not _directly_ related),
> there are packages [that organize namespaces]. 

+1.

But the CL package system is complex.  And RMS
has in the past nixed such a thing for Elisp.

You can use multiple obarrays in Elisp, but
that's about as far as any similarity goes.

Re: [ELPA] New package: transient

[João Távora]

On Sat, May 2, 2020 at 10:53 PM Drew Adams <drew.adams@oracle.com> wrote:
>
> > As you may know, in Common Lisp, a close
> > cousin to Elisp (though I think not _directly_ related),
> > there are packages [that organize namespaces].
>
> +1.
>
> But the CL package system is complex.  And RMS
> has in the past nixed such a thing for Elisp.

I remember that.  Yes, packages exist for a whole
lot more than just saving on typing. And newbies
trip on them over and over again, it's true.  But once
you get them, they're really good and they end up
solving lots of problems regarding encapsulation.

Maybe some reduced version of packages could
be invented, some file-local thing that configures the
READing of that file only. I remember some proposal
back then, right?

João

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > If the goal is to list all the functions related to manipulating the topic
  > of regexp (something like
  > https://docs.python.org/2/library/re.html#regular-expression-objects or
  > https://ruby-doc.org/core-2.7.1/Regexp.html), then the search you propose
  > is a poor tool.

I think you are making a distinction between names that are 
core parts of the use of regexps, and names that contain 'regexp'
because they stand for something that uses a regexp somehow.

Is that right?

And you expect the former to have names that start with 'regexp'
(although we have never had such a naming practice for data types).

Is that right?

Is the reason you expect the names to follow that pattern
that you are coming from a language that uses abstract object tyoes
where each type defines methods to operate on it?  Do you wish you
could ask, "Show me the operations defined on type 'regexp'"?

Lisp does not work that way, but I think we can set something up that
would give you more or less the same results for documentation.

  > I'm not objected to have aliases that would make it easier to find out
  > the function's name using simple completion, but I think you greatly
  > overestimate the usefulness of that in many practical situations.

I wouldn't want to rename lots if Lisp functions or fill up the namespace
with aliases, just so that names of functions which are "about alists"
all start with 'alist'.

But if it is just to make C-h f completion on 'alist' include 'assoc',
we don't need real aliases.  We could do it with aliaases that work
only in completion of function names.  We could make an alias
("alist" "assoc"), which would add "assoc" to the list
of completions of "alist".

These aliases would avoid the downsides completely.  Would they help you?


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It's been several time now that the "github community" proposed changes
  > that looked "evident improvements" to them but got hit by a wall of
  > incomprehension/complexity (I'm not saying this proposal is one of them,
  > but what comes often is "why not gitlab? how come s.el is not in Emacs
  > core?", etc).

I think the cause of the problem is that they are talking with each
other and not with us.  They have formed a separate community,
which may not have roots in Lisp and Emacs culture.

That separation will tend of cause problems.  How about if we
look for ways to bring the two communities together in discussion.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Stefan Monnier]

> I think the cause of the problem is that they are talking with each
> other and not with us.

They've also talked with us.

Emacs's core development is very averse to change.  So whenever someone
talks with us about change (whether coming from some hypothetical other
community or not), it's usually refused.

There are good reasons on both sides.  It's hard to reconcile the needs
of continuity with the desire to adapt to new practices.


        Stefan

Re: [ELPA] New package: transient

[Philippe Vaucher]

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

> I think you are making a distinction between names that are
> core parts of the use of regexps, and names that contain 'regexp'
> because they stand for something that uses a regexp somehow.
>
> Is that right?

Yes.

> And you expect the former to have names that start with 'regexp'
> (although we have never had such a naming practice for data types).
>
> Is that right?

Yes! :-)

> Is the reason you expect the names to follow that pattern
> that you are coming from a language that uses abstract object tyoes
> where each type defines methods to operate on it?  Do you wish you
> could ask, "Show me the operations defined on type 'regexp'"?

Yes, and also because in almost every other languages there are namespaces.
Including other lisps (Scheme, Clojure). Even in Emacs Lisp the namespace
concept is used, look at the all the `string-*` functions.

> But if it is just to make C-h f completion on 'alist' include 'assoc',
> we don't need real aliases.  We could do it with aliaases that work
> only in completion of function names.  We could make an alias
> ("alist" "assoc"), which would add "assoc" to the list
> of completions of "alist".
>
> These aliases would avoid the downsides completely.  Would they help you?

Maybe, I see that as being a bit dangerous and unexpected for a lot of
users tho. One expects plain text search in C-h f.

[-- Attachment #2: Type: text/html, Size: 1660 bytes --]

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: philippe.vaucher@gmail.com,  tomas@tuxteam.de,  rms@gnu.org,
>   emacs-devel@gnu.org
> Date: Sat, 02 May 2020 16:39:57 -0400
> 
> >> >> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
> >> >> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
> >> > Then "C-u C-h a WORDS..." is your friend.
> >> Nope, way too slow.
> > Is that the only problem? then let's speed it up, and Bob's our uncle.
> 
> When I say "slow" I measure the time in number of hand movements.
> I'm in the middle of writing code, I might have already written `str`
> even and now I'd have to do `C-u C-h a str mul RET` and that will only
> display the answer, I still have to find it in the list and then arrange
> for it to make its way to my buffer.
> 
> Compared to `-mul TAB`, I can't see any way the `C-h` route could be
> even remotely competitive.

You seem to be measuring only the "speed" of your typing the input,
and disregard the time required to look over the results of the
completion or doc search and decide which is the one you want.  By
contrast, what's important for me is the total time it took me to
request the completion/search and find the answer I was looking for.
So if a few additional keystrokes will give me the answer much more
quickly and accurately, it is a net win for me.

> No, because it lets you use a more targeted (non-substring) matching, so
> you'll have much fewer matches.

I will believe this when I see it.  For now, the proposals that are
floating will bloat the list, not make it shorter, and the fuzzy
matching in completion tends to bring more matches, not less.  For me,
any list where I don't find what I'm looking for within the first 2
dozen entries is "too long", and I tend to abandon it and look for
alternative ways of finding what I want.

> > The prefix convention we impose has almost nothing to do with the
> > issue at hand, because the package's name in many (most?) cases says
> > nothing about its domain of application.  E.g., take message.el or
> > tmm.el or windmove.el or tempo.el or xdg.el, to name just a few random
> > examples.
> 
> That's only unhelpful in the case where you don't know the relevant
> prefix name.  In such a situation, you definitely need to resort to some
> kind of manual to find your way to relevant library.
> 
> A regular/structured naming system doesn't help for that, but it helps
> afterwards: once you know under which prefix things should be found,
> then you can find the relevant function more easily.

I'm talking about the packages we actually have, and your
counter-argument seems to be that "in a better world" these
difficulties wouldn't happen.  But in this world they do happen: how
can anyone remember whether some window-related function is in
window.el, winner.el, or windmove.el?  Are we supposed to learn all
that by heart?

>         Stefan "who finds this discussion enlightening, because he took
>                 it for granted that everyone knows that such structuring
>                 is *obviously* good (tho not necessarily always best)."

Maybe you should use and hack Emacs more ;-)

Years of using Emacs with its superb documentation and elaborate
facilities to find stuff in that documentation caused me to be more
demanding, to expect better documentation that is easier to access
quickly.  I might compromise if something like that is not available
when I'm working with other software, but I certainly don't want to
give that up when I work on Emacs!  And I'm astonished to hear that
people don't _want_ the documentation we provide and the help commands
to go with it, and are willing to settle for API completion!

Re: [ELPA] New package: transient

[João Távora]

On Sun, May 3, 2020 at 3:45 PM Eli Zaretskii <eliz@gnu.org> wrote:
>
> Years of using Emacs with its superb documentation and elaborate
> facilities to find stuff in that documentation caused me to be more
> demanding, to expect better documentation that is easier to access
> quickly.  I might compromise if something like that is not available
> when I'm working with other software, but I certainly don't want to
> give that up when I work on Emacs!  And I'm astonished to hear that
> people don't _want_ the documentation we provide and the help commands
> to go with it, and are willing to settle for API completion!

While I agree with your stance on documentation, only recently did I
start learning a bit the new `C-h` commands.  Are they new-ish?
For many years it was only `C-h f` and `C-h v` for me. But I don't read
NEWS consistently, I admit, because it's very large and full of stuff
I don't care about.

Anyway travelling to the Elisp manual is usual a matter of:

M-x info RET C-s elisp RET RET C-s thing-im-hopeful-to-find C-s C-s

But the manual is so good that it's worth it, IMO.  But if it that
transfer could be made easier (maybe it already is?), that would
be great. Is there a help command that brings us to the Elisp
manual page on a non-command function?

My point it that the manual-savvy workflow should be better
advertised. Maybe some photogenic person among us could
make a screencast or something, that has a lot of impact.

João

Re: [ELPA] New package: transient

[Joost Kremers]

On Sun, May 03 2020, João Távora wrote:
> Anyway travelling to the Elisp manual is usual a matter of:
>
> M-x info RET C-s elisp RET RET C-s thing-im-hopeful-to-find C-s 
> C-s

C-h i m elisp RET i thing-im-hopeful-to-find RET

;-)



-- 
Joost Kremers
Life has its moments

Re: [ELPA] New package: transient

[Stefan Monnier]

>> >> >> Typical examples: is it `multibyte-string-p` or `string-multibyte-p`,
>> >> >> `file-name-absolute-p` or `absolute-file-name-p`, ... ?
>> >> > Then "C-u C-h a WORDS..." is your friend.
>> >> Nope, way too slow.
>> > Is that the only problem? then let's speed it up, and Bob's our uncle.
>> 
>> When I say "slow" I measure the time in number of hand movements.
>> I'm in the middle of writing code, I might have already written `str`
>> even and now I'd have to do `C-u C-h a str mul RET` and that will only
>> display the answer, I still have to find it in the list and then arrange
>> for it to make its way to my buffer.
>> 
>> Compared to `-mul TAB`, I can't see any way the `C-h` route could be
>> even remotely competitive.
>
> You seem to be measuring only the "speed" of your typing the input,
> and disregard the time required to look over the results of the
> completion or doc search and decide which is the one you want.

The examples I give are not hypothetical and I know those functions
very well.  I just have trouble remembering which permutation is used.
So there's no "look over the result" or "doc search" needed.  I don't
even need to bring up *Completions* at all.

> Maybe you should use and hack Emacs more ;-)
> Years of using Emacs with its superb documentation and elaborate

The documentation satisfies a different need.  This discussion is not
about replacing the manual with something else.


        Stefan

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Sun, 3 May 2020 16:03:33 +0100
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, tomas@tuxteam.de, 
> 	Richard Stallman <rms@gnu.org>, emacs-devel <emacs-devel@gnu.org>
> 
> While I agree with your stance on documentation, only recently did I
> start learning a bit the new `C-h` commands.  Are they new-ish?

No, most of them are very old.  We have "C-h d" since Emacs 22.1, for
example.  Some of them were added in Emacs 23 and 24.

> Anyway travelling to the Elisp manual is usual a matter of:
> 
> M-x info RET C-s elisp RET RET C-s thing-im-hopeful-to-find C-s C-s

My suggestion is to (a) always have the ELisp manual open in some
frame, and (b) look for whatever you need with the 'i' command,
possibly aided by TAB-completion.

> My point it that the manual-savvy workflow should be better
> advertised. Maybe some photogenic person among us could
> make a screencast or something, that has a lot of impact.

I'm all for it.

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 03.05.2020 17:45, Eli Zaretskii wrote:
> Years of using Emacs with its superb documentation and elaborate
> facilities to find stuff in that documentation caused me to be more
> demanding, to expect better documentation that is easier to access
> quickly.  I might compromise if something like that is not available
> when I'm working with other software, but I certainly don't want to
> give that up when I work on Emacs!  And I'm astonished to hear that
> people don't_want_  the documentation we provide and the help commands
> to go with it, and are willing to settle for API completion!

The main reason the discussion even went that way is because instead of 
acknowledging that the user's scenario is valid and the request is 
reasonable (that code completion and describe-function's completion will 
work easier and faster if function names are more predictable), you 
responded with the recommendations to "just use manual".

Whereas the manual provides a different workflow and doesn't cover all 
cases. For instance, it only covers the functions in the core. Maybe not 
even all of them. Whereas the aforementioned features work uniformly for 
all functions, no matter where defined or by whom.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: philippe.vaucher@gmail.com,  tomas@tuxteam.de,  rms@gnu.org,
>   emacs-devel@gnu.org
> Date: Sun, 03 May 2020 11:17:38 -0400
> 
> > You seem to be measuring only the "speed" of your typing the input,
> > and disregard the time required to look over the results of the
> > completion or doc search and decide which is the one you want.
> 
> The examples I give are not hypothetical

Neither are mine.

> The documentation satisfies a different need.  This discussion is not
> about replacing the manual with something else.

Not the manual, the help commands.  Maybe you should re-read the first
messages in this thread.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Cc: tomas@tuxteam.de, rms@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 3 May 2020 19:23:55 +0300
> 
> The main reason the discussion even went that way is because instead of 
> acknowledging that the user's scenario is valid and the request is 
> reasonable (that code completion and describe-function's completion will 
> work easier and faster if function names are more predictable), you 
> responded with the recommendations to "just use manual".

Not the manual, the documentation commands in general.  They don't
only use the manual.

And I don't see what's wrong with that.  I saw what I thought was the
wrong tool for the job, so I suggested to use a better tool.  Why do I
have to "acknowledge" a problem in using a wrong tool, instead of
pointing out that it's wrong?  Why is it "reasonable" to used the
wrong tool and expect that it produces optimal results?  It isn't.

> Whereas the manual provides a different workflow and doesn't cover all 
> cases. For instance, it only covers the functions in the core. Maybe not 
> even all of them.

You are preaching to the choir.  I didn't say to use the manual, I
said to use the C-h commands.

Re: [ELPA] New package: transient

[João Távora]

On Sun, May 3, 2020 at 5:25 PM Dmitry Gutov <dgutov@yandex.ru> wrote:
>
> On 03.05.2020 17:45, Eli Zaretskii wrote:
> > Years of using Emacs with its superb documentation and elaborate
> > facilities to find stuff in that documentation caused me to be more
> > demanding, to expect better documentation that is easier to access
> > quickly.  I might compromise if something like that is not available
> > when I'm working with other software, but I certainly don't want to
> > give that up when I work on Emacs!  And I'm astonished to hear that
> > people don't_want_  the documentation we provide and the help commands
> > to go with it, and are willing to settle for API completion!
>
> The main reason the discussion even went that way is because instead of
> acknowledging that the user's scenario is valid and the request is
> reasonable (that code completion and describe-function's completion will
> work easier and faster if function names are more predictable), you
> responded with the recommendations to "just use manual".
>
> Whereas the manual provides a different workflow and doesn't cover all
> cases. For instance, it only covers the functions in the core. Maybe not
> even all of them. Whereas the aforementioned features work uniformly for
> all functions, no matter where defined or by whom.

Yes, but isn't a step in reconciling the two workflows that the
aforementioned features be extracted from the manual?
Instead of going the hardcore, full frontal, bike shedding,
never-gonna-happen, "rename all the symbols" route?  I
mean I like those quick references too, but they're built,
probably automatically, for languages with different ways
of organizing code, that aren't available in Elisp right now.
That doesn't mean we can't have something that approaches
their usefulness without raping Lisp in the process.

Here are a few practical suggestions:

1. Make C-h O lookup a symbol's definition in the Elisp manual.
Is this very hard to do? Seems like it would make a nice parallel
to C-h F.

2. Make a Texinfo macro or something like that (completely ignorant here),
that extracts the listing of functions and or symbols under a given node.
This is the keep-lines example of Phillipe.

3. Make every function C-h f'ed whose provenance in the Elisp
manual we can automatically recognize have a link to the manual.

4. Make elisp--xref-backend collect references in the manual
(because why not?)

5. Make a "See also" section in the *Help* buffer.  Lars'
suggestion

João

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Sun, 3 May 2020 17:50:24 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>, tomas@tuxteam.de, 
> 	Richard Stallman <rms@gnu.org>, emacs-devel <emacs-devel@gnu.org>
> 
> 1. Make C-h O lookup a symbol's definition in the Elisp manual.
> Is this very hard to do? Seems like it would make a nice parallel
> to C-h F.

We already have "C-h S", doesn't it do what you want?

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 03.05.2020 19:47, Eli Zaretskii wrote:
> Not the manual, the documentation commands in general.  They don't
> only use the manual.

The apropos command has pretty much the same problem with filtering and 
ordering. Only more difficult, since it offers more matches.

Having function names more consistency named would help with it too.

Personal note: I don't like it's output. It's noisy and hard to scan 
visually. But that has little bearing on the argument.

> And I don't see what's wrong with that.  I saw what I thought was the
> wrong tool for the job, so I suggested to use a better tool.  Why do I
> have to "acknowledge" a problem in using a wrong tool, instead of
> pointing out that it's wrong?  Why is it "reasonable" to used the
> wrong tool and expect that it produces optimal results?  It isn't.

Calling a tool that many people have been employing for years 
"inadequate" is mildly insulting and dismissive of others' experience.

Even if I start using apropos and the manual more, I will continue using 
code completion and describe-xxx commands nevertheless, and better 
naming would still help there.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Cc: monnier@iro.umontreal.ca, tomas@tuxteam.de, rms@gnu.org,
>  emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 3 May 2020 20:04:38 +0300
> 
> The apropos command has pretty much the same problem with filtering and 
> ordering. Only more difficult, since it offers more matches.

It offers more matches because it finds what completion cannot.

> > And I don't see what's wrong with that.  I saw what I thought was the
> > wrong tool for the job, so I suggested to use a better tool.  Why do I
> > have to "acknowledge" a problem in using a wrong tool, instead of
> > pointing out that it's wrong?  Why is it "reasonable" to used the
> > wrong tool and expect that it produces optimal results?  It isn't.
> 
> Calling a tool that many people have been employing for years 
> "inadequate" is mildly insulting and dismissive of others' experience.

I'd rather expect that people would listen to better tools being
presented to them, and would consider using them to enrich their
experience and make their everyday's life better.  There's nothing
dismissive in providing answers to questions and pointing out how to
get some job done.  Otherwise, we'd need to consider entire forums
like help-gnu-emacs and reddit "dismissive" and "insulting", which I
think is absurd.

> Even if I start using apropos and the manual more, I will continue using 
> code completion and describe-xxx commands nevertheless, and better 
> naming would still help there.

It's okay to decide not to use some of the tools we have, if you don't
like them.  I'm talking to those who might decide otherwise.

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 03.05.2020 20:29, Eli Zaretskii wrote:
>> The apropos command has pretty much the same problem with filtering and
>> ordering. Only more difficult, since it offers more matches.
> It offers more matches because it finds what completion cannot.

See also what I wrote about apropos sorting.

>> Even if I start using apropos and the manual more, I will continue using
>> code completion and describe-xxx commands nevertheless, and better
>> naming would still help there.
> It's okay to decide not to use some of the tools we have, if you don't
> like them.  I'm talking to those who might decide otherwise.

Regardless of whether I regularly use the manual or not, it's not okay 
to dismiss subpar code completion experience just because we have 
separate commands that also do a more free-form search.

Re: [ELPA] New package: transient

[João Távora]

On Sun, May 3, 2020 at 5:55 PM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: João Távora <joaotavora@gmail.com>
> > Date: Sun, 3 May 2020 17:50:24 +0100
> > Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>, tomas@tuxteam.de,
> >       Richard Stallman <rms@gnu.org>, emacs-devel <emacs-devel@gnu.org>
> >
> > 1. Make C-h O lookup a symbol's definition in the Elisp manual.
> > Is this very hard to do? Seems like it would make a nice parallel
> > to C-h F.
>
> We already have "C-h S", doesn't it do what you want?

Yes! Yes.  </embarrassed>

Thanks :-)

Re: [ELPA] New package: transient

[Eli Zaretskii]

> Cc: monnier@iro.umontreal.ca, tomas@tuxteam.de, rms@gnu.org,
>  emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 3 May 2020 20:42:52 +0300
> 
> Regardless of whether I regularly use the manual or not, it's not okay 
> to dismiss subpar code completion experience just because we have 
> separate commands that also do a more free-form search.

Once again: I don't dismiss it, I'm trying to show that it's
sub-optimal for some jobs, in particular for discovery.

RE: [ELPA] New package: transient

[Drew Adams]

>> I think you are making a distinction between names that are
>> core parts of the use of regexps, and names that contain 'regexp'
>> because they stand for something that uses a regexp somehow.
>> Is that right?
>
> Yes.
>
>> And you expect the former to have names that start with 'regexp'
>> (although we have never had such a naming practice for data types).
>> Is that right?
>
> Yes! :-)
>
>> Is the reason you expect the names to follow that pattern
>> that you are coming from a language that uses abstract object tyoes
>> where each type defines methods to operate on it?  Do you wish you
>> could ask, "Show me the operations defined on type 'regexp'"?
>
> Yes, and also because in almost every other languages
> there are namespaces.  Including other lisps (Scheme,
> Clojure).

That's the rub/misunderstanding, I think.  That
namespaces are used does not imply that naming
need be based on object type.  In some languages -
in particular OOP - namespaces are based on types;
in other languages they're not.  Data types are
not the only way to group things.

> Even in Emacs Lisp the namespace concept is used,
> look at the all the `string-*` functions.

There are some, sure.  Nothing says that you
can't have a function that's mostly concerned
with a particular thing type.

And nothing says that in such a case we can't
put that type name in the function name.  But
it's not a requirement for all such functions,
let alone all or even most other functions.

And nothing says that `string' needs to be in
the prefix of such a function, as opposed to
somewhere else in its name.

Re: [ELPA] New package: transient

[João Távora]

On Sun, May 3, 2020 at 6:43 PM Dmitry Gutov <dgutov@yandex.ru> wrote:
> >> Even if I start using apropos and the manual more, I will continue using
> >> code completion and describe-xxx commands nevertheless, and better
> >> naming would still help there.
> Regardless of whether I regularly use the manual or not, it's not okay
> to dismiss subpar code completion experience just because we have
> separate commands that also do a more free-form search.

We really should work on the completion experience instead of naming.
If I can't drive straight, I'm not going to twist the road to compensate.

So, I get along quite nicely with flex + fido-mode with the current naming.
But that doesn't mean we can't improve the completion styles to be as
good as those that have a more free-form search. Reasonably simple
ML techniques come to mind for relevancy scoring, for example.

João

Re: [ELPA] New package: transient

[Stefan Monnier]

> And I don't see what's wrong with that.  I saw what I thought was the
> wrong tool for the job, so I suggested to use a better tool.

I get the impression that you misunderstand what is "the job".

From where I stand, documentation can help reduce the pain of
inconsistent naming, but it doesn't solve the underlying problem, so the
tools you suggest are "the wrong tools" ;-)


        Stefan

Re: [ELPA] New package: transient

[Stefan Monnier]

>> > You seem to be measuring only the "speed" of your typing the input,
>> > and disregard the time required to look over the results of the
>> > completion or doc search and decide which is the one you want.
>> The examples I give are not hypothetical
> Neither are mine.

But the above I meant that I don't understand the relevance of your
answer.  In the scenario of `string-multibyte-p` vs `multibyte-string-p`
or `absolute-file-name-p` vs `file-name-absolute-p` there is no "look
over the results".  I only do (or want to do) TAB completion.

>> The documentation satisfies a different need.  This discussion is not
>> about replacing the manual with something else.
> Not the manual, the help commands.

Neither one nor the other.  Nobody is talking about *replacing* anything
(other than replacing some names with others, admittedly ;-)

> Maybe you should re-read the first messages in this thread.

Yes, other people might be interested in other benefits of a more
regular/predictable/consistent naming scheme.  The benefits are multiple.


        Stefan

Re: [ELPA] New package: transient

[Stefan Monnier]

> That's the rub/misunderstanding, I think.  That
> namespaces are used does not imply that naming
> need be based on object type.

The propositions here aren't to group based on *types*.
Please stop those strawman arguments, again.

E.g. the `re-<foo>` renaming is not about any rind of "regular
expression type".  They're based on the same notions of namespacing used
in modules/packages/younameit, which is also the namespacing used in
Elisp packages, as a matter of fact, so it's really not a concept
foreign to Elisp.


        Stefan

Re: [ELPA] New package: transient

[João Távora]

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

On Sun, May 3, 2020, 22:18 Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> > That's the rub/misunderstanding, I think.  That
> > namespaces are used does not imply that naming
> > need be based on object type.
>
> The propositions here aren't to group based on *types*.
> Please stop those strawman arguments, again.


> E.g. the `re-<foo>` renaming is not about any rind of "regular
> expression type".  They're based on the same notions of namespacing used
> in modules/packages/younameit, which is also the namespacing used in
> Elisp packages, as a matter of fact, so it's really not a concept
> foreign to Elisp.


There's ambiguity in Elisp, there has always been. The first word can be
just a word or designate a namespace. The clearer the way the prefix
conveys which one of the two it means, the better.  But ambiguity because
of shared namespace is inevitable. So list- and string- are bad choices.
 process- and package- and request- are slightly better, if one momentarily
erases the verbs from one's mind. re- and rx- are better, though kinda
short. gnus-, eww- , yas- are great, IMO.

João

[-- Attachment #2: Type: text/html, Size: 1726 bytes --]

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 03.05.2020 22:49, João Távora wrote:
> We really should work on the completion experience instead of naming.
> If I can't drive straight, I'm not going to twist the road to compensate.

I can suggest a different analogy: if the road is twisted and full of 
holes, it doesn't matter how fast or reliable your car is. :-) You'll be 
late to your destination anyway.

> So, I get along quite nicely with flex + fido-mode with the current naming.
> But that doesn't mean we can't improve the completion styles to be as
> good as those that have a more free-form search.

I'm sure there's something to improve there, and more capability is 
always good, but when the user has to compensate for the API difficulty 
with specially-tweaked search terms, that's not too great either.

 > Reasonably simple
 > ML techniques come to mind for relevancy scoring, for example.

Usage-based sorting? I don't like that in general, and it doesn't fit 
all situations.

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 03.05.2020 21:58, Eli Zaretskii wrote:
>> Cc:monnier@iro.umontreal.ca,tomas@tuxteam.de,rms@gnu.org,
>>   emacs-devel@gnu.org
>> From: Dmitry Gutov<dgutov@yandex.ru>
>> Date: Sun, 3 May 2020 20:42:52 +0300
>>
>> Regardless of whether I regularly use the manual or not, it's not okay
>> to dismiss subpar code completion experience just because we have
>> separate commands that also do a more free-form search.
> Once again: I don't dismiss it, I'm trying to show that it's
> sub-optimal for some jobs, in particular for discovery.

It's generally the fastest way available (especially since with 
automatic code completion, it's often a side-effect of typing).

If the user tries it and it doesn't give a good result, they move on to 
the next one. But if we improve the percentage where the first one gives 
good results, it's an overall win in usability.

RE: [ELPA] New package: transient

[Drew Adams]

> > That's the rub/misunderstanding, I think.  That
> > namespaces are used does not imply that naming
> > need be based on object type.
> 
> The propositions here aren't to group based on *types*.
> Please stop those strawman arguments, again.

Please stop claiming that I'm making strawman
arguments.  That's certainly not my intention.

The idea that functions (many, some, whatever)
should be prefixed by the name of a particular
kind of thing - whether file-name, string, regexp,...
is what I'm talking about, and I've understood
that to be what at least some others have been
talking about (proposing).

That's different from the general idea of grouping.
And it's different from the general idea of using
a name prefix (of arbitrary nature: thing-kind or
not).  And it's different from the idea of using a
library prefix - which Emacs already has and uses.
(Existing library prefixes, especially 3rd-party,
can be all over the map, from an author's initials
to who-knows-what.)

Now you say that it's not about grouping and
prefixing functions that are related to the same
kind of thing.

OK.  In that case, yes, I've misunderstood.  Not a
straw man, but a wrong idea of what's been suggested.

> E.g. the `re-<foo>` renaming is not about any rind of "regular
> expression type".  They're based on the same notions of namespacing
> used in modules/packages/younameit, which is also the namespacing used in
> Elisp packages, as a matter of fact, so it's really not a concept
> foreign to Elisp.

If all you've meant is a library prefix then there's
nothing new.  Except perhaps if you intend to move
existing functions around and put all those you want
to change into libraries, renamed with prefixes.
I certainly didn't understand that as what was being
suggested.

If that's what you meant then is it your intention
that each such library would group only functions
for a particular kind of thing?  E.g. buffer-related
functions with prefix `buffer-' or `buf-' (e.g.)
in their own library, and so on for other kinds of
thing?  Or does it really have nothing to do with
grouping by thing-kind (and prefixing accordingly)?

I haven't seen a clear proposal, so perhaps you'll
forgive me for trying to guess what you and others
have meant, and guessing wrong (misunderstanding).

I've been under the impression that there's been a
suggestion, by some at least, to use a thing name
as the prefix.

And that can entail, for example, moving it to the
front from the middle of an existing name - e.g.
rename `multibyte-string-p` to `string-multibyte-p`,
to put `string' (the thing tested) first.

And I thought two of the arguments for that were
(1) consistency and (2) aid with completion (e.g.
many of the regexp functions with prefix `re-',
many of the string-related functions with prefix
`string-') - the latter point being that it can
help you find and access the functions concerned
with a given type/kind of thing.

If it's about a library prefix, is your idea to
have a library for regexp stuff, a library for
string stuff, etc., each with such a library prefix?

Frankly, what's proposed seems to be getting less
clear.   But maybe that's just me having difficulty
following.  You've said, regarding the string case,
that it's not about prefixing "string-manipulation"
functions, but it's been said to be about prefixing 
"string-related APIs".  Similarly, for regexps, I
thought.

I think I've made _my_ arguments clearly enough, so
perhaps I can stop here.  If they don't conflict
with what you want to do, great.  If they do, that's
OK too.  At this point I don't really know what you
want.  I guess I was mistaken before, in thinking I
knew.

In any case, believe me that I'm not trying to
misrepresent whatever it is that you're proposing,
as some straw-man argument to attack.  I thought I
was addressing what was being proposed.

Re: [ELPA] New package: transient

[João Távora]

On Mon, May 4, 2020 at 12:47 AM Dmitry Gutov <dgutov@yandex.ru> wrote:
>
> On 03.05.2020 22:49, João Távora wrote:
> > We really should work on the completion experience instead of naming.
> > If I can't drive straight, I'm not going to twist the road to compensate.
> I can suggest a different analogy: if the road is twisted and full of
> holes, it doesn't matter how fast or reliable your car is. :-) You'll be
> late to your destination anyway.

... and I'll stretch it some more: if you build more and more road you'll
just be left with cross-roads and no clear path.  So ditch the car,
get a mountain bike.

> I'm sure there's something to improve there, and more capability is
> always good, but when the user has to compensate for the API difficulty
> with specially-tweaked search terms, that's not too great either.

No special tweaking.  I mean users type "string" and they don't
miss any important string-only function and doesn't get
zibity-bob-stringy-string in the first results.  Emacs -Q +  fido-mode
I type C-f string and the only less relevant result i see is lgstring-char,
a super specific function from composite.el used multilangual
support.  _That_ should be renamed composite-lgstring-char.

Should the "string" results I get be grouped by arity, destructiveness
or some other sub-criteria? Maybe. flex knows nothing about that.
But it could if it really is useful.

I can even see a completion system where you type "alist" and "assq"
appears in the list by considering some source of truth (the manual).

>  > Reasonably simple
>  > ML techniques come to mind for relevancy scoring, for example.
> Usage-based sorting? I don't like that in general, and it doesn't fit
> all situations.

Don't see why. But let's for sake of argument say that I agree. What is
the problem we're trying to solve here?  Is it that there are functions
operators missing or just inconsistently named so newbies can't
find them? Eli has already shown they are grouped in the manual.
But some say newbies don't read manuals. Fine. You contend that
newbies use completion. Fine, then mix in info from the manual
into the sorting/grouping of completion results. Newbies prefer
API lists by topic? Then let's make those pretty lists from the
manual, again.

Really, let's first try that and have a good look at the results before
we decide renaming is the way to go, because that has serious
costs in mental overhead.

-- 
João Távora

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

> On May 4, 2020, at 2:29, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> I'd rather expect that people would listen to better tools being
> presented to them, and would consider using them to enrich their
> experience and make their everyday's life better.

Would you consider that a tutorial on the information search system provided by emacs would help in that matter ?


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: transient

[Dmitry Gutov]

On 04.05.2020 04:01, João Távora wrote:
> Emacs -Q +  fido-mode
> I type C-f string and the only less relevant result i see is lgstring-char,
> a super specific function from composite.el used multilangual
> support._That_  should be renamed composite-lgstring-char.

I gave some what I see as suboptimal examples. In this case, it's that, 
for example, rot13-string is sorted before string-to-syntax or 
string-prefix-p. But that's easy to fix: just ding all non-prefix 
matches's scores by 1.

> Fine. You contend that
> newbies use completion. Fine, then mix in info from the manual
> into the sorting/grouping of completion results. Newbies prefer
> API lists by topic? Then let's make those pretty lists from the
> manual, again.

I'm curious to see how that would look in code.

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

This inspiration struck me today.
(To part of the tune of America the Beautiful.)

O Emacs, how so beautiful?
Lisp shed its bikes on thee.
Uphold the names our minds have tamed;
Extend docs outside C.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > What's an alist?  It's a list.  What's a (true)
  > list?  It's a sequence.

  > `copy-sequence' (aka `copy-seq') also copies an
  > alist.

'copy-sequence' is usually not an adequate way to copy an alist.
It copies the backbone but not the associations.
When you modify the associations -- which you presumably intend to do --
the two copies will both be changed.

To copy an alist properly, you need to use 'copy-alist',
and that is why we added that function.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]


  > 2. Make a Texinfo macro or something like that (completely ignorant here),
  > that extracts the listing of functions and or symbols under a given node.
  > This is the keep-lines example of Phillipe.

The ELisp Manual index that lists functions
maps each function name into the node name
where it is described.
I think that gives exactly the data we would want for this.

What would this DO with that data?

Would someone like to try writing this?

  > 3. Make every function C-h f'ed whose provenance in the Elisp
  > manual we can automatically recognize have a link to the manual.

The same data would be usable for this job, I think.

Would someone like to try writing this?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I think the cause of the problem is that they are talking with each
  > > other and not with us.

  > They've also talked with us.

Your statement appears to disagree with mine, but not really --
due to the tenses, they are about slightly different points.

"They are talking with each other" is a statement about what they
_generally_ do, where as "they've talked with us" says they have
done something on at least one occasion.

I would guess that they talk with each other often, and only rarely
with us.  Is that correct?  If so, that is exactly the problem
situation I was concerned about.

If what they want is so different from what we want
that there is no possibility of cooperation, I think
it is a damned shame we didn't pay more attention early to
avoiding a fork.

But if there is still a chance of preserving some cooperation
with them, let's not be defeatist about it.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Is the reason you expect the names to follow that pattern
  > > that you are coming from a language that uses abstract object tyoes
  > > where each type defines methods to operate on it?  Do you wish you
  > > could ask, "Show me the operations defined on type 'regexp'"?

  > Yes, and also because in almost every other languages there are namespaces.
  > Including other lisps (Scheme, Clojure). Even in Emacs Lisp the namespace
  > concept is used, look at the all the `string-*` functions.

No, they are not namespaces.  What Emacs has is naming conventions.
They are flexible, not rigid.  They are suggestions, not rules.

We will not change Emacs to make them rigid rules, because we can't
stand for such regimentation.  But it isn't necessary.  We can provide
documentation facilities that do exactly what you want -- that list functions
_as if_ we had renamed functions to fit those rules.  You would then
be able to customize them, extend them, and modify them.

  >   We could make an alias
  > > ("alist" "assoc"), which would add "assoc" to the list
  > > of completions of "alist".
  > >
  > > These aliases would avoid the downsides completely.  Would they help you?

  > Maybe, I see that as being a bit dangerous and unexpected for a lot of
  > users tho. One expects plain text search in C-h f.

The text for that completion item could look like this

   alist-association (assoc)

Then the completion itself could be purely textual,
but if you select that item, what you would get in the minibuffer
would be 'assoc'.

It can work whichever way you like, and the way you prefer
could be installed as an option for users to choose.

Would that do what you need?



-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sun, 03 May 2020 17:04:21 -0400
> Cc: tomas@tuxteam.de, emacs-devel@gnu.org, rms@gnu.org,
>  Dmitry Gutov <dgutov@yandex.ru>
> 
> > And I don't see what's wrong with that.  I saw what I thought was the
> > wrong tool for the job, so I suggested to use a better tool.
> 
> I get the impression that you misunderstand what is "the job".
> 
> >From where I stand, documentation can help reduce the pain of
> inconsistent naming, but it doesn't solve the underlying problem, so the
> tools you suggest are "the wrong tools" ;-)

The "job" is discoverability.  A reminder how this started:

  Philippe Vaucher in https://lists.gnu.org/archive/html/emacs-devel/2020-04/msg01917.html:

>     > Overall I think it's a shame that the Emacs api wasn't designed with discoverability/consistency in mind
> 
>     Would you mind elaborate on this deficiency?  I don't think I quite
>     understand the complaint.
> 
> 
> It's hard to really criticize because Emacs was designed ages ago.
> 
> My point is simply this one: when I look at https://github.com/magnars/dash.el, https://github.com/NicolasPetton/seq.el or https://github.com/magnars/s.el I can immediately understand how the library works and how to achieve things. I can also easily use `C-h f` to find about the function I want.
> 
> In Emacs, parts of it are designed following the same principle, but a lot of it isn't:
> 
>     https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html sometimes assoc, alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` to discover the function I want? I can't, I have to go to that webpage and read it all.
>     https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Elements.html sometimes named logically (nth, remove, append), sometimes named after implementation detail (car, cdr), and no grouping at all so I can't `C-h f list TAB`

I submit that C-h documentation commands _are_ the tools for the job
of discoverability, and were actually mentioned at the very beginning
of this discussion.  The "consistent naming" was put forward as a
means to ease discoverability, so it is (allegedly) an alternative
tool for the same job.

Maybe I'm in the wrong discussion, but I was always talking about
discoverability and the best tools for that, as Philippe started.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: philippe.vaucher@gmail.com,  tomas@tuxteam.de,  rms@gnu.org,
>   emacs-devel@gnu.org
> Date: Sun, 03 May 2020 17:13:44 -0400
> 
> >> > You seem to be measuring only the "speed" of your typing the input,
> >> > and disregard the time required to look over the results of the
> >> > completion or doc search and decide which is the one you want.
> >> The examples I give are not hypothetical
> > Neither are mine.
> 
> But the above I meant that I don't understand the relevance of your
> answer.

And that is my problem because...?

> In the scenario of `string-multibyte-p` vs `multibyte-string-p`
> or `absolute-file-name-p` vs `file-name-absolute-p` there is no "look
> over the results".  I only do (or want to do) TAB completion.

No, you want to use that function whose name you don't really
remember.  Completion only helps if you have a pretty good idea about
the beginning of the name (and if there aren't a lot of other
candidates that begin the same).  In your case, completion cannot be
trusted up front; if you use it, you will lose time.

> >> The documentation satisfies a different need.  This discussion is not
> >> about replacing the manual with something else.
> > Not the manual, the help commands.
> 
> Neither one nor the other.  Nobody is talking about *replacing* anything
> (other than replacing some names with others, admittedly ;-)

Not entirely accurate.  The proposal is to replace (or, rather, add)
some names that will allow users to discover APIs using completion,
instead of using Help commands, which were designed for this job.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Mon, 4 May 2020 10:13:56 +0900
> Cc: Dmitry Gutov <dgutov@yandex.ru>,
>  tomas@tuxteam.de,
>  Emacs developers <emacs-devel@gnu.org>,
>  Stefan Monnier <monnier@iro.umontreal.ca>,
>  rms@gnu.org
> 
> > I'd rather expect that people would listen to better tools being
> > presented to them, and would consider using them to enrich their
> > experience and make their everyday's life better.
> 
> Would you consider that a tutorial on the information search system provided by 
> emacs would help in that matter ?

Maybe.  I don't think I understand well enough what would such a
tutorial include.  You didn't say.  We already have some of that ion
the Emacs tutorial, and then we have the "Help" chapter in the Emacs
manual.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Mon, 4 May 2020 02:01:13 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, tomas@tuxteam.de,
>  Stefan Monnier <monnier@iro.umontreal.ca>, Richard Stallman <rms@gnu.org>,
>  emacs-devel <emacs-devel@gnu.org>
> 
> [lgstring-char] should be renamed composite-lgstring-char

lgstring-char is an internal function, why do we care about its name?
It doesn't even have a doc string.  A better way with those is to
somehow mark them (perhaps by their symbol's property?), and make help
commands and completion avoid them by default.

OTOH, consider the use case of someone who would like to write
ligature support for Emacs (something which I hope will happen soon).
That person will need to find the various *lgstring* functions for the
job, even though they are internal, and naming them
composite-SOMETHING won't help them, since they will think of
ligatures, not of compositions.

I don't know how to solve this contradiction, but if we want our
completion to be a better tool, we should do something about these
conflicting goals.

> I can even see a completion system where you type "alist" and "assq"
> appears in the list by considering some source of truth (the manual).

It should be enough to look at the arguments as they appear in the doc
string.

Re: [ELPA] New package: transient

[Stefan Monnier]

>> >> The documentation satisfies a different need.  This discussion is not
>> >> about replacing the manual with something else.
>> > Not the manual, the help commands.
>> 
>> Neither one nor the other.  Nobody is talking about *replacing* anything
>> (other than replacing some names with others, admittedly ;-)
>
> Not entirely accurate.  The proposal is to replace (or, rather, add)
> some names that will allow users to discover APIs using completion,
> instead of using Help commands, which were designed for this job.

Right, replace some names.  Not replace the manual or the help commands
with something else.  It might make it possible for some people to
resort to the manual and help commands a bit less often, but that
doesn't mean it will replace them, just like the refcard doesn't
replace the manual, or eldoc doesn't replace the help commands.


        Stefan

Re: [ELPA] New package: transient

[Stefan Monnier]

> lgstring-char is an internal function, why do we care about its name?

That's a surprising answer: Imagine the author of `markdown-mode` were
to define a function `lgstring-foo`.  We don't disallow it, but we
strongly discourage such things.  Whether the function is "internal" to
the package or not doesn't make a difference to the fact that we do care
about its name.

So I think the better answer is that we just decided to use a separate
"lgstring-" prefix for those functions.


        Stefan "who's not bothered by the current naming in this respect"

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: philippe.vaucher@gmail.com,  tomas@tuxteam.de,  rms@gnu.org,
>   emacs-devel@gnu.org
> Date: Mon, 04 May 2020 11:14:41 -0400
> 
> >> >> The documentation satisfies a different need.  This discussion is not
> >> >> about replacing the manual with something else.
> >> > Not the manual, the help commands.
> >> 
> >> Neither one nor the other.  Nobody is talking about *replacing* anything
> >> (other than replacing some names with others, admittedly ;-)
> >
> > Not entirely accurate.  The proposal is to replace (or, rather, add)
> > some names that will allow users to discover APIs using completion,
> > instead of using Help commands, which were designed for this job.
> 
> Right, replace some names.  Not replace the manual or the help commands
> with something else.

Yes, replace documentation commands with completion, and renaming is
the means to that end.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: João Távora <joaotavora@gmail.com>,
>   dgutov@yandex.ru,
>   tomas@tuxteam.de,  rms@gnu.org,  emacs-devel@gnu.org
> Date: Mon, 04 May 2020 11:23:25 -0400
> 
> > lgstring-char is an internal function, why do we care about its name?
> 
> That's a surprising answer: Imagine the author of `markdown-mode` were
> to define a function `lgstring-foo`.  We don't disallow it, but we
> strongly discourage such things.

How is this different from the author of foo-mode defining a function
named copy-alist?

Every language has a set of reserved names.  In some languages, those
names are well-defined, in others they are less well-defined.  But
they are reserved nonetheless, and defining a function that already
exists without meaning to overload it is not a good idea.

(And anyway, how is this relevant to the issue at point?  Don't we
have enough of the deluge without adding tangents?)

RE: [ELPA] New package: transient

[Drew Adams]

>   > What's an alist?  It's a list.  What's a (true)
>   > list?  It's a sequence.
>   > `copy-sequence' (aka `copy-seq') also copies an
>   > alist.
> 
> 'copy-sequence' is usually not an adequate way to copy an alist.
> It copies the backbone but not the associations.
> When you modify the associations -- which you presumably intend
> to do -- the two copies will both be changed.
> 
> To copy an alist properly, you need to use 'copy-alist',
> and that is why we added that function.

Oh, right; forgot.  Thx.

(setq foo '((a . A))) ; foo is ((a . A))

(setq titi (copy-alist foo)) ; titi is ((a . A))
(setcdr (car titi) 'AA)      ; titi is ((a . AA))

foo is still ((a . A))

(setq bar (copy-sequence foo)) ; bar is ((a . A))
(setcdr (car bar) 'AA)         ; bar is ((a . AA))

foo is now   ((a . AA))

RE: [ELPA] New package: transient

[Drew Adams]

> I don't know how to solve this contradiction, but if we want our
> completion to be a better tool, we should do something about these
> conflicting goals.

Exactly.  Completion is many things, with many uses.
In one use case you want to see all such functions;
in another case you don't.

For code completion, you are mostly interested in
prefix completion (the prefix being the text just
before point).  For `C-h f' and other help commands
you might be interested in substring completion.

And so on.  There are many, many possibilities.

And then there's the question of whether it's only
a completion candidate as a name (string) or a
completion candidate as a key-value pair (e.g.
alist entry), where the value part can offer rich
info.  (Or a propertized string candidate.  Or a
symbol with plist data.  Or...)

And that's just completion.  When it comes to
doc/help, there are as many possibilities:
reference, API ref, guide, tutorial, video,...

Re: [ELPA] New package: transient

[João Távora]

On Mon, May 4, 2020 at 2:28 AM Dmitry Gutov <dgutov@yandex.ru> wrote:

> I gave some what I see as suboptimal examples. In this case, it's that,
> for example, rot13-string is sorted before string-to-syntax or
> string-prefix-p. But that's easy to fix: just ding all non-prefix
> matches's scores by 1.

Not horrible, but I'd rather boost by "also mentioned in the
manual" than penalize prefixes/suffixes.  Doing so would
demote rot13-string, lgstring-char, ad-docstring, for example.
Doing what you propose can be seen as yet another
way for the completion system to opine on how things should
be named. And that's fundamentally _not_ the problem we're
trying to solve.

Again, as far as I understand we're trying to solve "how do
discover related things" and "how to quickly reach for things
you know exist but don't can't predict/remember the name".
I think substring/flex completion (with those extra sprinkles)
is the  best way to do the latter.  It _can_ serve decently for
the  former, but I personally prefer the manual for that.

> > into the sorting/grouping of completion results. Newbies prefer
> > API lists by topic? Then let's make those pretty lists from the
> > manual, again.
> I'm curious to see how that would look in code.

I think we would have to enhance the @defun macro to
collect the definition into the a structure the organizes
definitions by node current node.  Then dump that information
in some section of the elisp manual. I thought the
@defun macro was under our control, but it's not.
No idea if Texinfo allows redefinition of macros, and in
fact very little idea of how Texinfo works at all, but I
this kind of things doesn't look very hard to do.  Maybe
Eli would like to comment.

João

Re: [ELPA] New package: transient

[Stefan Monnier]

>> Right, replace some names.  Not replace the manual or the help commands
>> with something else.
> Yes, replace documentation commands with completion, and renaming is
> the means to that end.

You say yes, I say no, and then we repeat:
let's agree that we misunderstand each other and move on.


        Stefan

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 04 May 2020 14:41:56 -0400
> Cc: tomas@tuxteam.de, rms@gnu.org, emacs-devel@gnu.org
> 
> let's agree that we misunderstand each other

Isn't it clear?

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

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



> On May 4, 2020, at 23:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Mon, 4 May 2020 10:13:56 +0900
>> Cc: Dmitry Gutov <dgutov@yandex.ru>,
>> tomas@tuxteam.de,
>> Emacs developers <emacs-devel@gnu.org>,
>> Stefan Monnier <monnier@iro.umontreal.ca>,
>> rms@gnu.org
>> 
>>> I'd rather expect that people would listen to better tools being
>>> presented to them, and would consider using them to enrich their
>>> experience and make their everyday's life better.
>> 
>> Would you consider that a tutorial on the information search system provided by emacs would help in that matter ?
> 
> Maybe.  I don't think I understand well enough what would such a
> tutorial include.  You didn't say.

What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.

> We already have some of that ion the Emacs tutorial

Very little in fact:

C-h t
C-h i
C-h f
C-h v
M-. → "requires running etags to record all the manuals nodes"
C-h p in a quote from the Emacs manual
M-x apropos
C-h a → the example Chassell gives produces 211 results

> and then we have the "Help" chapter in the Emacs manual.

The Help chapter provides a "summary of help commands for accessing the built-in documentation." That summary does not group the information by topic but merely lists the commands in the alphabetical order of the keys.

Let me attach a patch that groups the commands by topic (tables) in that summary. I am not sure adding a @subsection is the best way to label such groups (tables) but I could not find a better solution.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune



[-- Attachment #2: help.texi.200505.diff --]
[-- Type: application/octet-stream, Size: 6705 bytes --]

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 49c53c5cbc..ee7435fc13 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -86,94 +86,139 @@ Help Summary
 documentation.  Most of these are described in more detail in the
 following sections.
 
+@subsection Commands, functions, variables, symbols
+
 @table @kbd
 @item C-h a @var{topics} @key{RET}
 Display a list of commands whose names match @var{topics}
 (@code{apropos-command}).
-@item C-h b
-Display all active key bindings; minor mode bindings first, then those
-of the major mode, then global bindings (@code{describe-bindings}).
-@item C-h c @var{key}
-Show the name of the command that the key sequence @var{key} is bound
-to (@code{describe-key-briefly}).  Here @kbd{c} stands for
-``character''.  For more extensive information on @var{key}, use
-@kbd{C-h k}.
+
 @item C-h d @var{topics} @key{RET}
 Display the commands and variables whose documentation matches
 @var{topics} (@code{apropos-documentation}).
-@item C-h e
-Display the @file{*Messages*} buffer
-(@code{view-echo-area-messages}).
+
+@item C-h F @var{command} @key{RET}
+Enter Info and go to the node that documents the Emacs command
+@var{command} (@code{Info-goto-emacs-command-node}).
+
 @item C-h f @var{function} @key{RET}
 Display documentation on the Lisp function named @var{function}
 (@code{describe-function}).  Since commands are Lisp functions,
 this works for commands too.
-@item C-h h
-Display the @file{HELLO} file, which shows examples of various character
-sets.
-@item C-h i
-Run Info, the GNU documentation browser (@code{info}).  The Emacs
-manual is available in Info.
-@item C-h k @var{key}
-Display the name and documentation of the command that @var{key} runs
-(@code{describe-key}).
-@item C-h l
-Display a description of your last 300 keystrokes
-(@code{view-lossage}).
-@item C-h m
-Display documentation of the current major mode and minor modes
-(@code{describe-mode}).
-@item C-h n
-Display news of recent Emacs changes (@code{view-emacs-news}).
+
+@item C-h v @var{var} @key{RET}
+Display the documentation of the Lisp variable @var{var}
+(@code{describe-variable}).
+
 @item C-h o @var{symbol}
 Display documentation of the Lisp symbol named @var{symbol}
 (@code{describe-symbol}).  This will show the documentation of all
 kinds of symbols: functions, variables, and faces.
+
+@item C-h S @var{symbol} @key{RET}
+Display the Info documentation on symbol @var{symbol} according to the
+programming language you are editing (@code{info-lookup-symbol}).
+@end table
+
+@subsection Keys
+
+@table @kbd
+@item C-h b
+Display all active key bindings; minor mode bindings first, then those
+of the major mode, then global bindings (@code{describe-bindings}).
+
+@item C-h c @var{key}
+Show the name of the command that the key sequence @var{key} is bound
+to (@code{describe-key-briefly}).  Here @kbd{c} stands for
+``character''.  For more extensive information on @var{key}, use
+@kbd{C-h k}.
+
+@item C-h k @var{key}
+Display the name and documentation of the command that @var{key} runs
+(@code{describe-key}).
+
+@item C-h K @var{key}
+Enter Info and go to the node that documents the key sequence
+@var{key} (@code{Info-goto-emacs-key-command-node}).
+
+@item C-h w @var{command} @key{RET}
+Show which keys run the command named @var{command} (@code{where-is}).
+@end table
+
+@subsection Modes, packages
+
+@table @kbd
 @item C-h p
 Find packages by topic keyword (@code{finder-by-keyword}).  This lists
 packages using a package menu buffer.  @xref{Packages}.
+
 @item C-h P @var{package} @key{RET}
 Display documentation about the specified package
 (@code{describe-package}).
-@item C-h r
-Display the Emacs manual in Info (@code{info-emacs-manual}).
-@item C-h s
-Display the contents of the current @dfn{syntax table}
-(@code{describe-syntax}).  The syntax table says which characters are
-opening delimiters, which are parts of words, and so on.  @xref{Syntax
-Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
-details.
-@item C-h t
-Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
-@item C-h v @var{var} @key{RET}
-Display the documentation of the Lisp variable @var{var}
-(@code{describe-variable}).
-@item C-h w @var{command} @key{RET}
-Show which keys run the command named @var{command} (@code{where-is}).
+
+@item C-h m
+Display documentation of the current major mode and minor modes
+(@code{describe-mode}).
+@end table
+
+@subsection Input method, coding systems, languages
+
+@table @kbd
 @item C-h C @var{coding} @key{RET}
 Describe the coding system @var{coding}
 (@code{describe-coding-system}).
+
 @item C-h C @key{RET}
 Describe the coding systems currently in use.
-@item C-h F @var{command} @key{RET}
-Enter Info and go to the node that documents the Emacs command
-@var{command} (@code{Info-goto-emacs-command-node}).
+
 @item C-h I @var{method} @key{RET}
 Describe the input method @var{method} (@code{describe-input-method}).
-@item C-h K @var{key}
-Enter Info and go to the node that documents the key sequence
-@var{key} (@code{Info-goto-emacs-key-command-node}).
+
 @item C-h L @var{language-env} @key{RET}
 Display information on the character sets, coding systems, and input
 methods used in language environment @var{language-env}
 (@code{describe-language-environment}).
-@item C-h S @var{symbol} @key{RET}
-Display the Info documentation on symbol @var{symbol} according to the
-programming language you are editing (@code{info-lookup-symbol}).
+
+@item C-h h
+Display the @file{HELLO} file, which shows examples of various character
+sets.
+@end table
+
+@subsection Various information buffers
+
+@table @kbd
+@item C-h l
+Display a description of your last 300 keystrokes
+(@code{view-lossage}).
+
+@item C-h r
+Display the Emacs manual in Info (@code{info-emacs-manual}).
+
+@item C-h t
+Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
+
+@item C-h i
+Run Info, the GNU documentation browser (@code{info}) where all the
+installed info manuals can be found.
+
+@item C-h e
+Display the @file{*Messages*} buffer
+(@code{view-echo-area-messages}).
+
+@item C-h n
+Display news of recent Emacs changes (@code{view-emacs-news}).
+
 @item C-h .
 Display the help message for a special text area, if point is in one
 (@code{display-local-help}).  (These include, for example, links in
 @file{*Help*} buffers.)
+
+@item C-h s
+Display the contents of the current @dfn{syntax table}
+(@code{describe-syntax}).  The syntax table says which characters are
+opening delimiters, which are parts of words, and so on.  @xref{Syntax
+Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
+details.
 @end table
 
 @node Key Help

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

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



> On May 4, 2020, at 23:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Mon, 4 May 2020 10:13:56 +0900
>> Cc: Dmitry Gutov <dgutov@yandex.ru>,
>> tomas@tuxteam.de,
>> Emacs developers <emacs-devel@gnu.org>,
>> Stefan Monnier <monnier@iro.umontreal.ca>,
>> rms@gnu.org
>> 
>>> I'd rather expect that people would listen to better tools being
>>> presented to them, and would consider using them to enrich their
>>> experience and make their everyday's life better.
>> 
>> Would you consider that a tutorial on the information search system provided by emacs would help in that matter ?
> 
> Maybe.  I don't think I understand well enough what would such a
> tutorial include.  You didn't say.

What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.

> We already have some of that ion the Emacs tutorial

Very little in fact:

C-h t
C-h i
C-h f
C-h v
M-. → "requires running etags to record all the manuals nodes"
C-h p in a quote from the Emacs manual
M-x apropos
C-h a → the example Chassell gives produces 211 results

> and then we have the "Help" chapter in the Emacs manual.

The Help chapter provides a "summary of help commands for accessing the built-in documentation." That summary does not group the information by topic but merely lists the commands in the alphabetical order of the keys.

Let me attach a patch that groups the commands by topic (tables) in that summary. I am not sure adding a @subsection is the best way to label such groups (tables) but I could not find a better solution.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune



[-- Attachment #2: help.texi.200505.diff --]
[-- Type: application/octet-stream, Size: 6705 bytes --]

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 49c53c5cbc..ee7435fc13 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -86,94 +86,139 @@ Help Summary
 documentation.  Most of these are described in more detail in the
 following sections.
 
+@subsection Commands, functions, variables, symbols
+
 @table @kbd
 @item C-h a @var{topics} @key{RET}
 Display a list of commands whose names match @var{topics}
 (@code{apropos-command}).
-@item C-h b
-Display all active key bindings; minor mode bindings first, then those
-of the major mode, then global bindings (@code{describe-bindings}).
-@item C-h c @var{key}
-Show the name of the command that the key sequence @var{key} is bound
-to (@code{describe-key-briefly}).  Here @kbd{c} stands for
-``character''.  For more extensive information on @var{key}, use
-@kbd{C-h k}.
+
 @item C-h d @var{topics} @key{RET}
 Display the commands and variables whose documentation matches
 @var{topics} (@code{apropos-documentation}).
-@item C-h e
-Display the @file{*Messages*} buffer
-(@code{view-echo-area-messages}).
+
+@item C-h F @var{command} @key{RET}
+Enter Info and go to the node that documents the Emacs command
+@var{command} (@code{Info-goto-emacs-command-node}).
+
 @item C-h f @var{function} @key{RET}
 Display documentation on the Lisp function named @var{function}
 (@code{describe-function}).  Since commands are Lisp functions,
 this works for commands too.
-@item C-h h
-Display the @file{HELLO} file, which shows examples of various character
-sets.
-@item C-h i
-Run Info, the GNU documentation browser (@code{info}).  The Emacs
-manual is available in Info.
-@item C-h k @var{key}
-Display the name and documentation of the command that @var{key} runs
-(@code{describe-key}).
-@item C-h l
-Display a description of your last 300 keystrokes
-(@code{view-lossage}).
-@item C-h m
-Display documentation of the current major mode and minor modes
-(@code{describe-mode}).
-@item C-h n
-Display news of recent Emacs changes (@code{view-emacs-news}).
+
+@item C-h v @var{var} @key{RET}
+Display the documentation of the Lisp variable @var{var}
+(@code{describe-variable}).
+
 @item C-h o @var{symbol}
 Display documentation of the Lisp symbol named @var{symbol}
 (@code{describe-symbol}).  This will show the documentation of all
 kinds of symbols: functions, variables, and faces.
+
+@item C-h S @var{symbol} @key{RET}
+Display the Info documentation on symbol @var{symbol} according to the
+programming language you are editing (@code{info-lookup-symbol}).
+@end table
+
+@subsection Keys
+
+@table @kbd
+@item C-h b
+Display all active key bindings; minor mode bindings first, then those
+of the major mode, then global bindings (@code{describe-bindings}).
+
+@item C-h c @var{key}
+Show the name of the command that the key sequence @var{key} is bound
+to (@code{describe-key-briefly}).  Here @kbd{c} stands for
+``character''.  For more extensive information on @var{key}, use
+@kbd{C-h k}.
+
+@item C-h k @var{key}
+Display the name and documentation of the command that @var{key} runs
+(@code{describe-key}).
+
+@item C-h K @var{key}
+Enter Info and go to the node that documents the key sequence
+@var{key} (@code{Info-goto-emacs-key-command-node}).
+
+@item C-h w @var{command} @key{RET}
+Show which keys run the command named @var{command} (@code{where-is}).
+@end table
+
+@subsection Modes, packages
+
+@table @kbd
 @item C-h p
 Find packages by topic keyword (@code{finder-by-keyword}).  This lists
 packages using a package menu buffer.  @xref{Packages}.
+
 @item C-h P @var{package} @key{RET}
 Display documentation about the specified package
 (@code{describe-package}).
-@item C-h r
-Display the Emacs manual in Info (@code{info-emacs-manual}).
-@item C-h s
-Display the contents of the current @dfn{syntax table}
-(@code{describe-syntax}).  The syntax table says which characters are
-opening delimiters, which are parts of words, and so on.  @xref{Syntax
-Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
-details.
-@item C-h t
-Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
-@item C-h v @var{var} @key{RET}
-Display the documentation of the Lisp variable @var{var}
-(@code{describe-variable}).
-@item C-h w @var{command} @key{RET}
-Show which keys run the command named @var{command} (@code{where-is}).
+
+@item C-h m
+Display documentation of the current major mode and minor modes
+(@code{describe-mode}).
+@end table
+
+@subsection Input method, coding systems, languages
+
+@table @kbd
 @item C-h C @var{coding} @key{RET}
 Describe the coding system @var{coding}
 (@code{describe-coding-system}).
+
 @item C-h C @key{RET}
 Describe the coding systems currently in use.
-@item C-h F @var{command} @key{RET}
-Enter Info and go to the node that documents the Emacs command
-@var{command} (@code{Info-goto-emacs-command-node}).
+
 @item C-h I @var{method} @key{RET}
 Describe the input method @var{method} (@code{describe-input-method}).
-@item C-h K @var{key}
-Enter Info and go to the node that documents the key sequence
-@var{key} (@code{Info-goto-emacs-key-command-node}).
+
 @item C-h L @var{language-env} @key{RET}
 Display information on the character sets, coding systems, and input
 methods used in language environment @var{language-env}
 (@code{describe-language-environment}).
-@item C-h S @var{symbol} @key{RET}
-Display the Info documentation on symbol @var{symbol} according to the
-programming language you are editing (@code{info-lookup-symbol}).
+
+@item C-h h
+Display the @file{HELLO} file, which shows examples of various character
+sets.
+@end table
+
+@subsection Various information buffers
+
+@table @kbd
+@item C-h l
+Display a description of your last 300 keystrokes
+(@code{view-lossage}).
+
+@item C-h r
+Display the Emacs manual in Info (@code{info-emacs-manual}).
+
+@item C-h t
+Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
+
+@item C-h i
+Run Info, the GNU documentation browser (@code{info}) where all the
+installed info manuals can be found.
+
+@item C-h e
+Display the @file{*Messages*} buffer
+(@code{view-echo-area-messages}).
+
+@item C-h n
+Display news of recent Emacs changes (@code{view-emacs-news}).
+
 @item C-h .
 Display the help message for a special text area, if point is in one
 (@code{display-local-help}).  (These include, for example, links in
 @file{*Help*} buffers.)
+
+@item C-h s
+Display the contents of the current @dfn{syntax table}
+(@code{describe-syntax}).  The syntax table says which characters are
+opening delimiters, which are parts of words, and so on.  @xref{Syntax
+Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
+details.
 @end table
 
 @node Key Help

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Tue, 5 May 2020 17:23:24 +0900
> 
> >> Would you consider that a tutorial on the information search system provided by emacs would help in that matter ?
> > 
> > Maybe.  I don't think I understand well enough what would such a
> > tutorial include.  You didn't say.
> 
> What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.

If you mean a tutorial for the Info mode, then we already have it:
info.info.  You can get to it if you type 'h' in Info mode.

> > We already have some of that ion the Emacs tutorial
> 
> Very little in fact:
> 
> C-h t
> C-h i
> C-h f
> C-h v
> M-. → "requires running etags to record all the manuals nodes"
> C-h p in a quote from the Emacs manual
> M-x apropos
> C-h a → the example Chassell gives produces 211 results

I think you are looking at the Introduction to Programming in Emacs
Lisp, not at the tutorial.

> > and then we have the "Help" chapter in the Emacs manual.
> 
> The Help chapter provides a "summary of help commands for accessing the built-in documentation."

That's just the summary section.  The next sections describe the
commands in detail.

> That summary does not group the information by topic but merely lists the commands in the alphabetical order of the keys.
> 
> Let me attach a patch that groups the commands by topic (tables) in that summary. I am not sure adding a @subsection is the best way to label such groups (tables) but I could not find a better solution.

Thanks, but in long lists of loosely-related items, it is usually
better to arrange them in alphabetical order, since it makes it easier
to find what you need.

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

> On May 5, 2020, at 23:48, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Let me attach a patch that groups the commands by topic (tables) in that summary. I am not sure adding a @subsection is the best way to label such groups (tables) but I could not find a better solution.
> 
> Thanks, but in long lists of loosely-related items, it is usually
> better to arrange them in alphabetical order, since it makes it easier
> to find what you need.

The items are not loosely related once grouped and the list is not long.

This is not an index but a summary: a list of items arguably selected for their importance. Putting the list arbitrarily in alphabetical order adds to its complexity.

I don't understand what you mean.

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

> On May 5, 2020, at 23:48, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Tue, 5 May 2020 17:23:24 +0900
>> 
>>>> Would you consider that a tutorial on the information search system provided by emacs would help in that matter ?
>>> 
>>> Maybe.  I don't think I understand well enough what would such a
>>> tutorial include.  You didn't say.
>> 
>> What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.
> 
> If you mean a tutorial for the Info mode, then we already have it:
> info.info.  You can get to it if you type 'h' in Info mode.

No, I mean a tutorial on the "information *search* system".

>>> We already have some of that ion the Emacs tutorial
>> 
>> Very little in fact:
>> 
>> C-h t
>> C-h i
>> C-h f
>> C-h v
>> M-. → "requires running etags to record all the manuals nodes"
>> C-h p in a quote from the Emacs manual
>> M-x apropos
>> C-h a → the example Chassell gives produces 211 results
> 
> I think you are looking at the Introduction to Programming in Emacs
> Lisp, not at the tutorial.

The tutorial has even less information.

>>> and then we have the "Help" chapter in the Emacs manual.
>> 
>> The Help chapter provides a "summary of help commands for accessing the built-in documentation."
> 
> That's just the summary section.  The next sections describe the
> commands in detail.

I saw that.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Wed, 6 May 2020 00:39:41 +0900
> 
> > Thanks, but in long lists of loosely-related items, it is usually
> > better to arrange them in alphabetical order, since it makes it easier
> > to find what you need.
> 
> The items are not loosely related once grouped and the list is not long.

The list is almost 30 items long.

> Putting the list arbitrarily in alphabetical order adds to its complexity.

Sorry, I disagree.  And we had in the past bug reports that requested
alphabetical order in similar list (I don't remember if this one was
one of them), so I think people generally like this better.

Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Wed, 6 May 2020 00:44:07 +0900
> 
> >> What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.
> > 
> > If you mean a tutorial for the Info mode, then we already have it:
> > info.info.  You can get to it if you type 'h' in Info mode.
> 
> No, I mean a tutorial on the "information *search* system".

Then I still don't have a clear idea of what kind of tutorial you had
in mind, sorry.

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

> On May 6, 2020, at 1:13, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Wed, 6 May 2020 00:39:41 +0900
>> 
>>> Thanks, but in long lists of loosely-related items, it is usually
>>> better to arrange them in alphabetical order, since it makes it easier
>>> to find what you need.
>> 
>> The items are not loosely related once grouped and the list is not long.
> 
> The list is almost 30 items long.

And it's shorter now because items are grouped.

Have you actually taken a look at the patch ?


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: transient

[Jean-Christophe Helary]

> On May 6, 2020, at 1:15, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Wed, 6 May 2020 00:44:07 +0900
>> 
>>>> What a tutorial usually includes is step-by-step help with practical examples. I'll be putting that on my todo list.
>>> 
>>> If you mean a tutorial for the Info mode, then we already have it:
>>> info.info.  You can get to it if you type 'h' in Info mode.
>> 
>> No, I mean a tutorial on the "information *search* system".
> 
> Then I still don't have a clear idea of what kind of tutorial you had
> in mind, sorry.

Too bad, but in the end you're not the kind of person who'd benefit from it (or only indirectly I guess). So I'll just do my stuff and post it somewhere.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune