Gather a list of confusions beginner tend to have

Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

> I think everybody would agree on attracting more people to use
> Emacs—that means more blogs and help, more contributor, etc. And
> people agree that Emacs isn’t as beginner-friendly as it could be. The
> problem is what to improve, and how.

Not necessarily.  Personally, I don’t see much benefit in trying to
appeal users that have no background in coding whatsoever, and users who
wouldn’t really benefit from what Emacs has to offer.

> As the first step, we should collect real experiences from real
> beginners: someone starts to use Emacs just recently (e.g., less than
> one year).

The major problem is that someone who fiddled with Emacs now and
couldn’t make use of it may think differently when a couple years later
they have some knowledge of programming (not necessarily professionally)
and some experience with other tools.

Anecdotally, I’ve picked up and quit Emacs multiple times before I
decided to stay with it.  And it’s been more than 6 years now that I’m
using it for the good part of my computing.  What was puzzling and weird
to me back then is useful and essential to me now.

What I mean is, what is good for newcomers, who are not guaranteed to
stay, can be irrelevant, not so good, or even off-putting to actual
users of this package of software.  Emacs is a power tool, and like all
power tools, requires two preconditions to be useful: 1) the user should
*need* the tool, and 2) the user should be willing to put in the time to
learn the tool.  And a good power tool is designed with user who need
and use them the most in mind.

IDK. IMHO, we shouldn’t break stuff in Emacs itself, and maybe promote
distros for people that want a more "modern" experience instead.  They
don’t have the backwards compatibility baggage of Emacs so they will do
it better than Emacs core nevertheless.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Gather a list of confusions beginner tend to have

[Yuan Fu]

> On Sep 8, 2020, at 2:48 PM, Göktuğ Kayaalp <self@gkayaalp.com> wrote:
> 
> 
>> I think everybody would agree on attracting more people to use
>> Emacs—that means more blogs and help, more contributor, etc. And
>> people agree that Emacs isn’t as beginner-friendly as it could be. The
>> problem is what to improve, and how.
> 
> Not necessarily.  Personally, I don’t see much benefit in trying to
> appeal users that have no background in coding whatsoever, and users who
> wouldn’t really benefit from what Emacs has to offer.
> 
>> As the first step, we should collect real experiences from real
>> beginners: someone starts to use Emacs just recently (e.g., less than
>> one year).
> 
> The major problem is that someone who fiddled with Emacs now and
> couldn’t make use of it may think differently when a couple years later
> they have some knowledge of programming (not necessarily professionally)
> and some experience with other tools.
> 
> Anecdotally, I’ve picked up and quit Emacs multiple times before I
> decided to stay with it.  And it’s been more than 6 years now that I’m
> using it for the good part of my computing.  What was puzzling and weird
> to me back then is useful and essential to me now.
> 
> What I mean is, what is good for newcomers, who are not guaranteed to
> stay, can be irrelevant, not so good, or even off-putting to actual
> users of this package of software.  Emacs is a power tool, and like all
> power tools, requires two preconditions to be useful: 1) the user should
> *need* the tool, and 2) the user should be willing to put in the time to
> learn the tool.  And a good power tool is designed with user who need
> and use them the most in mind.
> 
> IDK. IMHO, we shouldn’t break stuff in Emacs itself, and maybe promote
> distros for people that want a more "modern" experience instead.  They
> don’t have the backwards compatibility baggage of Emacs so they will do
> it better than Emacs core nevertheless.
> 
> --
> İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
> pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427
> 

I generally agree with your point. However, what I have in mind is not changing defaults, but rather a configuration wizard, that can prompt user and let him select from Emacs binding vs CUA binding, Emacs undo vs simple undo/redo, themes, etc. I’ve seen such wizard in Intellj Idea, Spacemacs, etc. Something like (just an example):


----------------------------------------------------------------------

Set UI themes:

<some C code>

- [ ] default
- [ ] dark
- [ ] ...

----------------------------------------------------------------------

Keybinding notation:

    C (control)   Ctrl
    M (meta)      Alt/Option
    s (super)     Windows/Command
    S (shift)     Shift

Set keybinding style for copy/paste:

[ ] default

    M-w           Copy
    C-y           Paste
    C-w           Cut

[ ] alternative

    C-c           Copy
    C-v           Paste
    C-x           Cut


[Next] [Skip]

----------------------------------------------------------------------

[ ] Enable line numbers

[ ] Use thin cursor

[ ] Disable tool bar

[ ] Disable scroll bar


[Next] [Skip]

----------------------------------------------------------------------

Emacs has a powerful (but possibly unintuitive) undo system, where
undo operations themselves are recorded in the undo history, and redo
is done by undoing an previous undo operation.

Set undo style:

[ ] default

    C-/           Undo

[ ] linear

    C-/           Undo
    C-?           Redo

[ ] alternative

    C-z           Undo
    C-S-z         Redo


[Next] [Skip]

----------------------------------------------------------------------

Additional packages:

[ ] Company

      Popup completion.
      <gif>


[ ] Ivy

      Completion for opening files, executing commands, etc.
      <gif>


[ ] Expand-region

      Incrementally expand selection.
      <gif>


[ ] Which-key

      Shows possible keybindings.
      <gif>
      

[Finish]  You can re-run this guide by M-x beginner-guide RET


Yuan

Re: Gather a list of confusions beginner tend to have

[Praharsh Suryadevara]

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

Hello,
I've been an emacs user for ~3 years. While I'm now used to the defaults, I
do remember in some detail, the pain it took me to get used to the
keybindings in vanilla emacs .

I think the sore points other than the undo/redo, were C-f not being bound
to find, (though that would need remapping forward-char), C-o not being
bound open file. I do think it might make sense to poll on reddit. and
again to clarify _(I don't think any of these ideas would break backward
compatibility, but instead only add options to increase familiarity with
vanilla emacs for new users)_

@yuan I was following the threads earlier and I checked the idea of a
profile was suggested
https://lists.gnu.org/archive/html/emacs-devel/2020-04/msg02032.html, I
think a starter wizard could go well with this as a base for keymaps at
least if you're thinking about implementing it (?). The other thing I was
thinking was maybe you could write directly to init.el with use-package
with comments in an understandable manner following the discussion
about custom here
https://lists.gnu.org/archive/html/emacs-devel/2020-09/msg00306.html. I
think this would teach and encourage users to tweak their configurations
which I think would be a win-win.

I would be willing to contribute some time to this.

Thanks,
Praharsh






On Tue, Sep 8, 2020 at 2:31 PM Yuan Fu <casouri@gmail.com> wrote:

>
>
> > On Sep 8, 2020, at 2:48 PM, Göktuğ Kayaalp <self@gkayaalp.com> wrote:
> >
> >
> >> I think everybody would agree on attracting more people to use
> >> Emacs—that means more blogs and help, more contributor, etc. And
> >> people agree that Emacs isn’t as beginner-friendly as it could be. The
> >> problem is what to improve, and how.
> >
> > Not necessarily.  Personally, I don’t see much benefit in trying to
> > appeal users that have no background in coding whatsoever, and users who
> > wouldn’t really benefit from what Emacs has to offer.
> >
> >> As the first step, we should collect real experiences from real
> >> beginners: someone starts to use Emacs just recently (e.g., less than
> >> one year).
> >
> > The major problem is that someone who fiddled with Emacs now and
> > couldn’t make use of it may think differently when a couple years later
> > they have some knowledge of programming (not necessarily professionally)
> > and some experience with other tools.
> >
> > Anecdotally, I’ve picked up and quit Emacs multiple times before I
> > decided to stay with it.  And it’s been more than 6 years now that I’m
> > using it for the good part of my computing.  What was puzzling and weird
> > to me back then is useful and essential to me now.
> >
> > What I mean is, what is good for newcomers, who are not guaranteed to
> > stay, can be irrelevant, not so good, or even off-putting to actual
> > users of this package of software.  Emacs is a power tool, and like all
> > power tools, requires two preconditions to be useful: 1) the user should
> > *need* the tool, and 2) the user should be willing to put in the time to
> > learn the tool.  And a good power tool is designed with user who need
> > and use them the most in mind.
> >
> > IDK. IMHO, we shouldn’t break stuff in Emacs itself, and maybe promote
> > distros for people that want a more "modern" experience instead.  They
> > don’t have the backwards compatibility baggage of Emacs so they will do
> > it better than Emacs core nevertheless.
> >
> > --
> > İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
> > pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427
> >
>
> I generally agree with your point. However, what I have in mind is not
> changing defaults, but rather a configuration wizard, that can prompt user
> and let him select from Emacs binding vs CUA binding, Emacs undo vs simple
> undo/redo, themes, etc. I’ve seen such wizard in Intellj Idea, Spacemacs,
> etc. Something like (just an example):
>
>
> ----------------------------------------------------------------------
>
> Set UI themes:
>
> <some C code>
>
> - [ ] default
> - [ ] dark
> - [ ] ...
>
> ----------------------------------------------------------------------
>
> Keybinding notation:
>
>     C (control)   Ctrl
>     M (meta)      Alt/Option
>     s (super)     Windows/Command
>     S (shift)     Shift
>
> Set keybinding style for copy/paste:
>
> [ ] default
>
>     M-w           Copy
>     C-y           Paste
>     C-w           Cut
>
> [ ] alternative
>
>     C-c           Copy
>     C-v           Paste
>     C-x           Cut
>
>
> [Next] [Skip]
>
> ----------------------------------------------------------------------
>
> [ ] Enable line numbers
>
> [ ] Use thin cursor
>
> [ ] Disable tool bar
>
> [ ] Disable scroll bar
>
>
> [Next] [Skip]
>
> ----------------------------------------------------------------------
>
> Emacs has a powerful (but possibly unintuitive) undo system, where
> undo operations themselves are recorded in the undo history, and redo
> is done by undoing an previous undo operation.
>
> Set undo style:
>
> [ ] default
>
>     C-/           Undo
>
> [ ] linear
>
>     C-/           Undo
>     C-?           Redo
>
> [ ] alternative
>
>     C-z           Undo
>     C-S-z         Redo
>
>
> [Next] [Skip]
>
> ----------------------------------------------------------------------
>
> Additional packages:
>
> [ ] Company
>
>       Popup completion.
>       <gif>
>
>
> [ ] Ivy
>
>       Completion for opening files, executing commands, etc.
>       <gif>
>
>
> [ ] Expand-region
>
>       Incrementally expand selection.
>       <gif>
>
>
> [ ] Which-key
>
>       Shows possible keybindings.
>       <gif>
>
>
> [Finish]  You can re-run this guide by M-x beginner-guide RET
>
>
> Yuan
>
>
>
>

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

Re: Gather a list of confusions beginner tend to have

[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 sore points other than the undo/redo, were C-f not being bound
  > to find, (though that would need remapping forward-char), C-o not being
  > bound open file.

Thanks for telling us; that information may be useful.
Your experience was what it was, and cannot be denied.

It is not an option to change these basic key bindings to imitate
other, newer editors.  It would create a different editor that we
Emacs users would never switch to.  It is unfortunate that the people
who implemented the newer editors chose incompatibility with Emacs.

But I have an idea for how to teach beginners those keys.

Suppose that C-f ran a command that displayed this:

   Want to move forward?  Type C-f again.  Search is C-s.

After that, successive C-f's would move forward as usual.

The idea is you'd be given that binding by default as a beginner,
and you'd turn it off once you had learned C-f and C-s.

C-o could do something similar, saying

   Want to open a line?  Type C-o again.  Find File is C-x C-f.

Would you have found that helpful?


  > @yuan I was following the threads earlier and I checked the idea of a
  > profile was suggested
  > https://lists.gnu.org/archive/html/emacs-devel/2020-04/msg02032.html, I
  > think a starter wizard could go well with this as a base for keymaps at
  > least if you're thinking about implementing it (?).

I know in general what the word "profile" means, but what is your
concrete suggestion?  Also, what concretely would a "starter wizard"
do?

-- 
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: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 08 Sep 2020 23:51:30 -0400
> Cc: self@gkayaalp.com, casouri@gmail.com, emacs-devel@gnu.org
> 
> But I have an idea for how to teach beginners those keys.
> 
> Suppose that C-f ran a command that displayed this:
> 
>    Want to move forward?  Type C-f again.  Search is C-s.
> 
> After that, successive C-f's would move forward as usual.
> 
> The idea is you'd be given that binding by default as a beginner,
> and you'd turn it off once you had learned C-f and C-s.
> 
> C-o could do something similar, saying
> 
>    Want to open a line?  Type C-o again.  Find File is C-x C-f.
> 
> Would you have found that helpful?

The reason we didn't put these on the splash screen is because we have
a menu bar, where everyone can find these popular commands without the
need to read any instructions.  Who will not know nowadays that to
open a file, one need to click on "File" and look in the menu that
drops down from that?

What we put on the splash screen is stuff that is harder to come by,
and/or that is more important to have in the user's face.

Re: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On 2020-09-09 17:18 +03, Eli Zaretskii <eliz@gnu.org> wrote:
> The reason we didn't put these on the splash screen is because we have
> a menu bar, where everyone can find these popular commands without the
> need to read any instructions.  Who will not know nowadays that to
> open a file, one need to click on "File" and look in the menu that
> drops down from that?

It looks like some of the starter kits / distributions are disabling
menu and toolbars.

We might ask them that they at least don’t disable menu-bar-mode by
default if that’s the case.


-- 
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Gather a list of confusions beginner tend to have

[Stefan Kangas]

Göktuğ Kayaalp <self@gkayaalp.com> writes:

> It looks like some of the starter kits / distributions are disabling
> menu and toolbars.
>
> We might ask them that they at least don’t disable menu-bar-mode by
> default if that’s the case.

Yes, this is a good idea.

It would be very useful if someone could report this as a bug to the top
five or ten most used distributions/starter kits that do this.

Re: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On 2020-09-09 18:07 +03, Stefan Kangas <stefankangas@gmail.com> wrote:
> Yes, this is a good idea.
>
> It would be very useful if someone could report this as a bug to the top
> five or ten most used distributions/starter kits that do this.

If there’s consensus that this is something we should do I’d volunteer
for identifying the projects and opening the issues.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Gather a list of confusions beginner tend to have

[Praharsh Suryadevara]

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

I agree

On Wed, Sep 9, 2020 at 11:09 AM Göktuğ Kayaalp <self@gkayaalp.com> wrote:

> On 2020-09-09 18:07 +03, Stefan Kangas <stefankangas@gmail.com> wrote:
> > Yes, this is a good idea.
> >
> > It would be very useful if someone could report this as a bug to the top
> > five or ten most used distributions/starter kits that do this.
>
> If there’s consensus that this is something we should do I’d volunteer
> for identifying the projects and opening the issues.
>
> --
> İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
> pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427
>

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

Re: Gather a list of confusions beginner tend to have

[Praharsh Suryadevara]

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

I think that could be one reason why. A friend set me up with a starter kit
later. Before that, I made a few attempts at vanilla emacs and gave up and
I did not realize CUA mode existed until yesterday.
I understand it'd be much more helpful if I remembered the details, but
it's been a while and I'm used to and very happy with the emacs defaults
now. A more useful method would be to put a friend/colleague who's never
used emacs in front of vanilla emacs and observe them figure it out (I'm
sure some of us may have put them in front of it already).

The point I believe in is, *It possible to make emacs easier for new users
to be able to start working in emacs from the beginning without sacrificing
any functionality for old users*
This need not come from changing the defaults, but rather from a startup
wizard or a profile which *sets the bindings/preferences according to what
the user wants.*
This is useful *because a new user won't know enough e-lisp to make the
editor do what he/she/they can work with.*

As for startup wizards, I was talking about what Yuan was proposing (
https://en.wikipedia.org/wiki/Wizard_(software)), a series of dialog boxes
that would introduce new users to emacs and give them a setup that they
could work with.

@tomas While I understand your point, I think there's a difference between
switching from emacs to vim/ vice versa (I don't complain about vim
keybindings after using emacs and I wouldn't expect people to complain vice
versa) and a new user who's only used C-x and C-c for cut and paste for all
their life being exposed to emacs (or vim).

@Eli As for options for the configuration wizard, If I were to assume I was
the audience being targeted when I started (an early 20s physics undergrad
who wrote basic python and wanted a good LaTeX editor), I think I would be
minimally happy with CUA mode with some basic AUCTeX setup. Maybe, some of
the minimal options would be easy to flesh out?


Thanks,
Praharsh




On Wed, Sep 9, 2020 at 9:24 AM Göktuğ Kayaalp <self@gkayaalp.com> wrote:

> On 2020-09-09 17:18 +03, Eli Zaretskii <eliz@gnu.org> wrote:
> > The reason we didn't put these on the splash screen is because we have
> > a menu bar, where everyone can find these popular commands without the
> > need to read any instructions.  Who will not know nowadays that to
> > open a file, one need to click on "File" and look in the menu that
> > drops down from that?
>
> It looks like some of the starter kits / distributions are disabling
> menu and toolbars.
>
> We might ask them that they at least don’t disable menu-bar-mode by
> default if that’s the case.
>
>
> --
> İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
> pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427
>

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

Re: Gather a list of confusions beginner tend to have

[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 point I believe in is, *It possible to make emacs easier for new users
  > to be able to start working in emacs from the beginning without sacrificing
  > any functionality for old users*
  > This need not come from changing the defaults, but rather from a startup
  > wizard or a profile which *sets the bindings/preferences according to what
  > the user wants.*

It sounds nice in principle.  However, rebinding keys in Emacs is hard
because the space of bindings is so populated.  You have to delete the
binding for some command.  As a beginner you might think that is easy
since there are so many keys you will never use -- but the commands
you guessed you don't want might be keys you will later want to learn.

-- 
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: Gather a list of confusions beginner tend to have

[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 reason we didn't put these on the splash screen is because we have
  > a menu bar, where everyone can find these popular commands without the
  > need to read any instructions.  Who will not know nowadays that to
  > open a file, one need to click on "File" and look in the menu that
  > drops down from that?

That argument seems quite persuasive, but it doesn't seem to apply
to everyone.

Someone (was it self@gkayaalp.com?) wrote about expecting O to visit a
file; that is what I responded to.  Whoever I responded to, if you are
reading this,, could you tell us why the existence of the menu did not
make it obvious how to visit a file?

-- 
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: Gather a list of confusions beginner tend to have

[Praharsh Suryadevara]

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

Because the starter kit a friend set me up with (graphene) after I couldn't
use vanilla emacs removed it.  self@gkayaalp.com addressed the issue.

On Thu, Sep 10, 2020 at 11:13 PM Richard Stallman <rms@gnu.org> wrote:

> [[[ 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 reason we didn't put these on the splash screen is because we have
>   > a menu bar, where everyone can find these popular commands without the
>   > need to read any instructions.  Who will not know nowadays that to
>   > open a file, one need to click on "File" and look in the menu that
>   > drops down from that?
>
> That argument seems quite persuasive, but it doesn't seem to apply
> to everyone.
>
> Someone (was it self@gkayaalp.com?) wrote about expecting O to visit a
> file; that is what I responded to.  Whoever I responded to, if you are
> reading this,, could you tell us why the existence of the menu did not
> make it obvious how to visit a file?
>
> --
> 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)
>
>
>

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

Re: Gather a list of confusions beginner tend to have

[tomas]

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

On Tue, Sep 08, 2020 at 04:30:57PM -0500, Praharsh Suryadevara wrote:
> Hello,
> I've been an emacs user for ~3 years. While I'm now used to the defaults, I
> do remember in some detail, the pain it took me to get used to the
> keybindings in vanilla emacs .
> 
> I think the sore points other than the undo/redo, were C-f not being bound
> to find [...]

But that's it, exactly. I moved to Emacs from vi (later elvis, vim).
I /knew/ it was going to be painful, but I never complained `find'
wasn't bound to '/'.

It's difficult to draw the line between "make more user-friendly"
and "do as I am accustomed to". The latter will end up following
some trend which, compared to Emacs's longevity, will always be a
fad.

Witness: CUA. Most people think these days "CUA" means: "Copy" [1]
is bound to "C-c", "Cut" [2] is bound to "C-x" and "Paste" [3] to
"C-v".

But according to IBM's "Common User Architecture" (aka "CUA" [4]),
it's "C-Insert", "S-Del", and "S-Ins" respectively. But Apple's [5]
infantilised version ("C-x" is the "scissors", etc.) somehow snuck
in.

Don't get me wrong -- I do recognise value in trying to harmonise
user interfaces across applications. But consistency whithin one
application and stability over time are also values to be taken
into account. In the end, it will be a balance act, with one (or
several, that's what distributions are for!) equilibrium points,
which themselves vary over time.

What Emacs can do is to provide a solid base and all the freedom
of configurability. And Emacs does deliver on that.

Cheers

[1] called in Emacs "kill-ring-save"
[2] called in Emacs "kill"
[3] "yank", in Emacs
[4] https://en.wikipedia.org/wiki/Common_User_Access
[5] I guess they stole it from Smalltalk, as everything
   else, too.

 - t

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

Re: Gather a list of confusions beginner tend to have

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

  > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
  > it's "C-Insert", "S-Del", and "S-Ins" respectively.

We might want to implement these bindings.  Then we can say ttat Emacs
supports the CUA spec, with a reference to it.

It may not please the real users ;-{, but it would refute the claims
that we don't support CUA.  We could explain that CUA stands for
Cover Ur Ass.
;-!

-- 
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: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 09 Sep 2020 22:40:39 -0400
> Cc: emacs-devel@gnu.org
> 
>   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
>   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
> 
> We might want to implement these bindings.

Actually, we already have these bindings by default.

Re: Gather a list of confusions beginner tend to have

[tomas]

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

On Thu, Sep 10, 2020 at 06:32:59AM +0300, Eli Zaretskii wrote:
> > From: Richard Stallman <rms@gnu.org>
> > Date: Wed, 09 Sep 2020 22:40:39 -0400
> > Cc: emacs-devel@gnu.org
> > 
> >   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
> >   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
> > 
> > We might want to implement these bindings.
> 
> Actually, we already have these bindings by default.

Hm. The manual didn't tell me... should have it?

Cheers
 - t

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

Re: Gather a list of confusions beginner tend to have

[Gregory Heytings via Emacs development discussions.]

>>>> But according to IBM's "Common User Architecture" (aka "CUA" [4]), 
>>>> it's "C-Insert", "S-Del", and "S-Ins" respectively.
>>>
>>> We might want to implement these bindings.
>>
>> Actually, we already have these bindings by default.
>
> Hm. The manual didn't tell me... should have it?
>

With vanilla Emacs you have indeed (see C-h w):

kill-ring-save is on <C-insertchar>, <C-insert>, M-w, <menu-bar> <edit> <copy>
yank is on C-y, <S-insertchar>, <S-insert>, <menu-bar> <edit> <paste>
kill-region is on C-w, <S-delete>, <menu-bar> <edit> <cut>

So the CUA bindings are there.

Re: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> Date: Thu, 10 Sep 2020 09:08:09 +0000
> From: Gregory Heytings via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> With vanilla Emacs you have indeed (see C-h w):
> 
> kill-ring-save is on <C-insertchar>, <C-insert>, M-w, <menu-bar> <edit> <copy>
> yank is on C-y, <S-insertchar>, <S-insert>, <menu-bar> <edit> <paste>
> kill-region is on C-w, <S-delete>, <menu-bar> <edit> <cut>
> 
> So the CUA bindings are there.

But not the "CUA bindings" that users out there expect, which is what
we call "CUA mode".

IOW, historical precedents and naming mistakes aside, many newcomers
expect the likes of C-c, C-v, C-a, C-z, C-x to do what they do in
other applications, and we only provide those when CUA Mode is turned
on, we cannot possibly provide them by default.

So the fact that IBM calls "CUA" something else is a tangent, not
really relevant or important in this context.

Re: Gather a list of confusions beginner tend to have

[tomas]

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

On Thu, Sep 10, 2020 at 12:34:14PM +0300, Eli Zaretskii wrote:
> > Date: Thu, 10 Sep 2020 09:08:09 +0000
> > From: Gregory Heytings via "Emacs development discussions." <emacs-devel@gnu.org>
> > 
> > With vanilla Emacs you have indeed (see C-h w):
> > 
> > kill-ring-save is on <C-insertchar>, <C-insert>, M-w, <menu-bar> <edit> <copy>
> > yank is on C-y, <S-insertchar>, <S-insert>, <menu-bar> <edit> <paste>
> > kill-region is on C-w, <S-delete>, <menu-bar> <edit> <cut>
> > 
> > So the CUA bindings are there.
> 
> But not the "CUA bindings" that users out there expect, which is what
> we call "CUA mode".

Definitely. I didn't intend to imply otherwise. Rather I wanted to
remind people that "there is not a Right GUI", and that it changes
over time depending on whoever dominates whatever market out there.

The quintessence of my message is that there's a price to pay when
following those changing conventions (after all, there are lots of
Emacs users who use, e.g. C-c for something else!), and thus changing
a default always will take discussion, patience, and perhaps accepting
that the outcome isn't always what one wants.

[...]

> So the fact that IBM calls "CUA" something else is a tangent, not
> really relevant or important in this context.

I don't even think they care about it anymore ;-)
> 

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

Re: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> Date: Thu, 10 Sep 2020 10:29:28 +0200
> From: tomas@tuxteam.de
> Cc: rms@gnu.org, emacs-devel@gnu.org
> 
> > >   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
> > >   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
> > > 
> > > We might want to implement these bindings.
> > 
> > Actually, we already have these bindings by default.
> 
> Hm. The manual didn't tell me... should have it?

Which manual, and in what place in that manual?

Re: Gather a list of confusions beginner tend to have

[tomas]

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

On Thu, Sep 10, 2020 at 12:30:51PM +0300, Eli Zaretskii wrote:
> > Date: Thu, 10 Sep 2020 10:29:28 +0200
> > From: tomas@tuxteam.de
> > Cc: rms@gnu.org, emacs-devel@gnu.org
> > 
> > > >   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
> > > >   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
> > > > 
> > > > We might want to implement these bindings.
> > > 
> > > Actually, we already have these bindings by default.
> > 
> > Hm. The manual didn't tell me... should have it?
> 
> Which manual, and in what place in that manual?

The Emacs Manual, 12.6 "CUA Bindings", fairly recent:

   This is the ‘GNU Emacs Manual’, updated for Emacs version 28.0.50.

   Copyright © 1985–1987, 1993–2020 Free Software Foundation, Inc.

But as stated elsewhere in the thread, it's perhaps not that
important. Shift-INS and friends have at most historical value
these days, I guess.

Cheers
 - t

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

Re: Gather a list of confusions beginner tend to have

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

  > >   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
  > >   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
  > > 
  > > We might want to implement these bindings.

  > Actually, we already have these bindings by default.

I tested them with C-h k, on a tty using its function keys, and they
did not have those bindings.  I am using master from June.


-- 
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: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: tomas@tuxteam.de, emacs-devel@gnu.org
> Date: Fri, 11 Sep 2020 00:18:52 -0400
> 
>   > >   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
>   > >   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
>   > > 
>   > > We might want to implement these bindings.
> 
>   > Actually, we already have these bindings by default.
> 
> I tested them with C-h k, on a tty using its function keys, and they
> did not have those bindings.  I am using master from June.

We have them on GUI frames.

Re: Gather a list of confusions beginner tend to have

[Stefan Monnier]

>>   > >   > But according to IBM's "Common User Architecture" (aka "CUA" [4]),
>>   > >   > it's "C-Insert", "S-Del", and "S-Ins" respectively.
>>   > > We might want to implement these bindings.
>>   > Actually, we already have these bindings by default.
>> I tested them with C-h k, on a tty using its function keys, and they
>> did not have those bindings.  I am using master from June.
> We have them on GUI frames.

I think we also have them in tty frames, but many/most terminals are not
able to transmit those keys properly.


        Stefan

Re: Gather a list of confusions beginner tend to have

[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 tested them with C-h k, on a tty using its function keys, and they
  > > did not have those bindings.  I am using master from June.

  > We have them on GUI frames.

Shouldn't those bindings be the same on tty frames?
There seem to have no meaningful binding on tty frames now.
-- 
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: Gather a list of confusions beginner tend to have

[Emanuel Berg via Emacs development discussions.]

Richard Stallman wrote:

> Shouldn't those bindings be the same on tty frames?
> There seem to have no meaningful binding on tty
> frames now.

In /etc/console-setup/remap.inc:

  # example: make F3 work in tty Emacs
  keycode 61 = U+1001

in an Elisp file:

  ;; example: make F3 work in tty Emacs
  (define-key input-decode-map [?\u1001] [func3])
  (global-set-key [func3] (lambda () (interactive) (message "F3")))

See:

  https://dataswamp.org/~incal/conf/remap.inc
  https://dataswamp.org/~incal/emacs-init/console-keys.el
  https://dataswamp.org/~incal/tty-emacs-keys.txt

--
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Gather a list of confusions beginner tend to have

[tomas]

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

On Wed, Sep 09, 2020 at 10:40:39PM -0400, Richard Stallman wrote:

[...]

> It may not please the real users ;-{, but it would refute the claims
> that we don't support CUA.  We could explain that CUA stands for
> Cover Ur Ass.
> ;-!

:-)

OTOH... who wants to do /that/ with IBM?

Cheers
 - t

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

Re: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Tue, 8 Sep 2020 15:30:56 -0400
> Cc: emacs-devel@gnu.org
> 
> I generally agree with your point. However, what I have in mind is not changing defaults, but rather a configuration wizard, that can prompt user and let him select from Emacs binding vs CUA binding, Emacs undo vs simple undo/redo, themes, etc. I’ve seen such wizard in Intellj Idea, Spacemacs, etc. Something like (just an example):
> 
> 
> ----------------------------------------------------------------------
> 
> Set UI themes:
> 
> <some C code>
> 
> - [ ] default
> - [ ] dark
> - [ ] ...
> 
> ----------------------------------------------------------------------
> 
> Keybinding notation:
> 
>     C (control)   Ctrl
>     M (meta)      Alt/Option
>     s (super)     Windows/Command
>     S (shift)     Shift

I don't think this scales.  Emacs has thousands of options, I'm
guessing hundreds of them are important for the audience you have in
mind.  You will get a huge set of many options that people with
"TL;DR" state of mind will never be able to review, let alone decide
what is for them.

The grouping of the options must be based on some "themes" or similar,
to be useful.  The challenge is, of course, to come up with a useful
list of such "themes", and then decide which options should each theme
enable.

Re: Gather a list of confusions beginner tend to have

[Yuan Fu]

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

> 
> I don't think this scales.  Emacs has thousands of options, I'm
> guessing hundreds of them are important for the audience you have in
> mind.  You will get a huge set of many options that people with
> "TL;DR" state of mind will never be able to review, let alone decide
> what is for them.

I think there are a few configurations that a beginner would want to change right after he starts Emacs, usually very basic settings. If you think it’s a good idea, I can go to reddit and ask what people missed when then started using Emacs for the first few minutes. 

FWIW, here is a demo of the guide: https://youtu.be/0qMskTAR2aw

The demo inserts some configurations into ~/.emacs.d/init.el after completion.

> 
> The grouping of the options must be based on some "themes" or similar,
> to be useful.  The challenge is, of course, to come up with a useful
> list of such "themes", and then decide which options should each theme
> enable.

Others has described the out-of-the-box experience of doom Emacs, it seems to me that such job is better done by a “distribution” of Emacs than by vanilla Emacs. OTHO, vanilla Emacs could add a tiny guide like I proposed to more or less improve the life for those who started Emacs without reading any tutorial on the internet.

Yuan


[-- Attachment #2: beginner-guide.el --]
[-- Type: application/octet-stream, Size: 11363 bytes --]

;;; beginner-guide.el --- Beginner guide for Emacs      -*- lexical-binding: t; -*-

;; Author: Yuan Fu <casouri@gmail.com>

;;; This file is NOT part of GNU Emacs

;;; Commentary:
;;

;;; Code:
;;

(require 'widget)

(eval-when-compile
  (require 'wid-edit))

(defvar beginner-guide--config-intro
  ";; Below is the configuration generated by the beginner guide:\n"
  "First line of the beginner guide configuration in init.el.")

(defvar beginner-guide--config-outro
  ";; The configuration generated by the beginner guide ends here.\n"
  "Last line of the beginner guide configuration in init.el.")

(defun beginner-guide--write-config (form-list)
  "Create ~/.emacs.d/init.el and write FORM-LIST into it."
  (mkdir "~/.emacs.d" 'no-error)
  (let ((init-file (expand-file-name "init.el" user-emacs-directory)))
    (with-current-buffer (find-file-noselect init-file t)
      (goto-char (point-min))
      (when (search-forward beginner-guide--config-intro nil t)
        (let ((beg (match-beginning 0)))
          (when (search-forward beginner-guide--config-outro nil t)
            (delete-region beg (point))
            (save-buffer))))
      (goto-char (point-max))
      (insert "\n" beginner-guide--config-intro)
      (dolist (form form-list)
        (prin1 form (current-buffer))
        (insert "\n"))
      (insert beginner-guide--config-outro)
      (save-buffer))))

(defvar beginner-guide--config nil
  "An alist of configurations that the user set in each page.")

(defsubst beginner-guide--save-option (option value)
  "Save OPTION’s VALUE in ‘beginner-guide--config’."
  (setf (alist-get option beginner-guide--config) value))


;;; Pages

;;;; Theme

(defvar beginner-guide--c-demo
  "int add (int x, int y)
{
  return x + y;
}

int main(int arg, int* argv)
{
  int x = 1;
  int y = 2;
  return add(x, y) - 3;
}
"
  "Demo C code.")

(defun beginner-guide--theme-page ()
  "Theme configuration page."
  (let ((inhibit-read-only t))
    (erase-buffer))
  (remove-overlays)
  (widget-insert "Set UI theme:\n\n")
  ;; Insert a C demo.
  (widget-insert
   (with-temp-buffer
     (insert beginner-guide--c-demo)
     (c-mode)
     (font-lock-fontify-region (point-min) (point-max))
     (buffer-string)))
  (widget-insert "\n")
  ;; Insert theme selection menu.
  (apply #'widget-create 'radio-button-choice
         :follow-link t
         :value "default"
         ;; Enable the theme when the user selects it.
         :notify (lambda (widget &rest _)
                   (mapc #'disable-theme custom-enabled-themes)
                   (let ((theme (intern (widget-value widget))))
                     ;; Load theme.
                     (unless (eq theme 'default)
                       (load-theme theme))
                     ;; Set config.
                     (beginner-guide--save-option 'theme theme)))
         (cons '(item "default")
               (cl-loop for theme in (custom-available-themes)
                        collect `(item ,(symbol-name theme)))))
  (use-local-map widget-keymap)
  (widget-setup))

;;;; Keybinding

(defun beginner-guide--keybinding-page ()
  "Keybinding page."
  (widget-insert "Keybinding notation:

    C (control)   Ctrl
    M (meta)      Alt/Option
    s (super)     Windows/Command
    S (shift)     Shift

Set keybinding style for copy/paste:

We encourage you to learn the default binding, because the alternative
binding conflicts with many parts of Emacs and make the experience
worse in the long run.\n\n")
  (widget-create 'radio-button-choice
                 :follow-link t
                 :value "default"
                 :notify (lambda (widget &rest _)
                           (beginner-guide--save-option
                            'keybinding (widget-value widget)))
                 '(item :value "default"
                        :format "%v\n\n%d\n"
                        :doc "    M-w           Copy
    C-y           Paste
    C-w           Cut
    C-s           Search
    C-x C-s       Save")
                 '(item :value "alternative"
                        :format "%v\n\n%d\n"
                        :doc "    C-c           Copy
    C-v           Paste
    C-x           Cut
    C-f           Search
    C-s           Save")))

;;;; UI features

(defun beginner-guide--ui-features-page ()
  "UI features page."
  (widget-insert "Set some UI options:\n\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (global-display-line-numbers-mode
                              (if val 1 -1))
                             (beginner-guide--save-option
                              'line-number val)))
                 :value nil)
  (widget-insert " Enable line numbers.\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (setq-default cursor-type
                                           (if val 'bar t))
                             (beginner-guide--save-option
                              'thin-cursor val)))
                 :value nil)
  (widget-insert " Use thin cursor bar.\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (tool-bar-mode (if val -1 1))
                             (beginner-guide--save-option
                              'disable-tool-bar val)))
                 :value nil)
  (widget-insert " Disable tool bar.\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (scroll-bar-mode (if val -1 1))
                             (beginner-guide--save-option
                              'disable-scroll-bar val)))
                 :value nil)
  (widget-insert " Disable scroll bar.\n"))

;;;; Undo

(defun beginner-guide--undo-page ()
  "Undo page."
  (widget-insert
   "Emacs has a powerful (but possibly unintuitive) undo system, where
undo operations themselves are recorded in the undo history, and redo
is done by undoing an previous undo operation.

Set undo style:\n\n")
  (widget-create 'radio-button-choice
                 :value "default"
                 :follow-lint t
                 :notify (lambda (widget &rest _)
                           (beginner-guide--save-option
                            'undo-style (widget-value widget)))
                 '(item :value "default"
                        :format "%v\n\n%d\n"
                        :doc "    C-/           Undo")
                 '(item :value "linear"
                        :format "%v\n\n%d\n"
                        :doc "    C-/           Undo
    C-?           Redo")
                 '(item :value "alternative"
                        :format "linear with alternative binding\n\n%d"
                        :doc "    C-z           Undo
    C-S-z         Redo")))

;;;; Guide

(defun beginner-guide--with-boilerplate
    (setup-fn &optional page-list finish-fn)
  "Call page setup function, SETUP-FN, with Customize boilerplate.
PAGE-LIST is a list of setup function for pages to show in a series.
FINISH-FN is called when user clicks the finish button."
  (let ((inhibit-read-only t))
    (erase-buffer))
  (remove-overlays)
  (funcall setup-fn)
  (widget-insert "\n\n")
  (beginner-guide--insert-step-buttons setup-fn page-list finish-fn)
  (use-local-map widget-keymap)
  (widget-setup)
  (goto-char (point-min)))

(defun beginner-guide--insert-step-buttons (page page-list finish-fn)
  "Insert buttons that go to previous and next page of PAGE.
PAGE-LIST is a list of setup function for pages to show in a series.
Insert a Button that calls FINISH-FN at the last page."
  (let* ((idx (seq-position page-list page))
         (previous-page (if (eq idx 0) nil
                          (nth (1- idx) page-list)))
         (next-page (nth (1+ idx) page-list)))
    (widget-insert (format "%s/%s " (1+ idx) (length page-list)))
    (when previous-page
      (widget-create
       'push-button
       :notify (lambda (&rest _)
                 (beginner-guide--with-boilerplate
                  previous-page page-list finish-fn))
       :value "Back"))
    (widget-insert " ")
    (if next-page
        (widget-create
         'push-button
         :notify (lambda (&rest _)
                   (beginner-guide--with-boilerplate
                    next-page page-list finish-fn))
         :value "Next")
      (widget-create
       'push-button
       :notify (lambda (&rest _) (funcall finish-fn))
       :value "Finish"))
    (widget-insert "\n")))

(defun beginner-guide--generate-config (config-alist)
  "Generate configuration code from CONFIG-ALIST."
  (cl-loop for option in '(theme keybinding line-number thin-cursor
                                 disable-tool-bar scroll-bar
                                 undo-style)
           append
           (let ((value (alist-get option config-alist)))
             (pcase (list option value)
               (`(theme ,theme) (unless (eq theme 'default))
                `((load-theme ',theme)))
               ('(keybinding "alternative")
                '((global-set-key (kbd "C-c") #'kill-ring-save)
                  (global-set-key (kbd "C-v") #'yank)
                  (global-set-key (kbd "C-x") #'kill-region)
                  (global-set-key (kbd "C-f") #'isearch-forward)
                  (global-set-key (kbd "C-s") #'save-buffer)))
               ('(line-number t)
                '((global-display-line-numbers-mode)))
               ('(thin-cursor t)
                '((setq-default cursor-type 'bar)))
               ('(disable-tool-bar t)
                '((tool-bar-mode -1)))
               ('(disable-scroll-bar t)
                '((scroll-bar-mode -1)))
               ('(undo-style "linear")
                '((global-set-key (kbd "C-/") #'undo-only)
                  (global-set-key (kbd "C-?") #'undo-redo)))
               ('(undo-style "alternative")
                '((global-set-key (kbd "C-z") #'undo-only)
                  (global-set-key (kbd "C-S-z") #'undo-redo)))
               ))))

(defun beginner-guide ()
  "Run the beginner guide."
  (interactive)
  (switch-to-buffer (get-buffer-create "*beginner guide*"))
  (setq beginner-guide--config nil)
  (let ((page-list '(beginner-guide--theme-page
                     beginner-guide--keybinding-page
                     beginner-guide--ui-features-page
                     beginner-guide--undo-page)))
    (beginner-guide--with-boilerplate
     (car page-list) page-list
     (lambda ()
       (kill-buffer)
       (with-temp-file "~/tmp/init.el"
         (let ((form-list (beginner-guide--generate-config
                           beginner-guide--config)))
           (mapc #'eval form-list)
           (beginner-guide--write-config form-list)))))))

(provide 'beginner-guide)

;;; beginner-guide.el ends here

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

Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Stefan Kangas]

Yuan Fu <casouri@gmail.com> writes:

> I think there are a few configurations that a beginner would want to
> change right after he starts Emacs, usually very basic settings. If
> you think it’s a good idea, I can go to reddit and ask what people
> missed when then started using Emacs for the first few minutes.
>
> FWIW, here is a demo of the guide: https://youtu.be/0qMskTAR2aw
>
> The demo inserts some configurations into ~/.emacs.d/init.el after completion.

Such a beginners guide (wizard) is an excellent idea.  And it is great
that you actually have code.  Let's see what others think, but I will
optimistically add my comments below.

To my mind, your draft has about the right amount of complexity and
options, but we should consider carefully what to include.

I propose to consider if any of these are suitable for inclusion:

- scroll-conservatively, visible-bell
- desktop-save-mode, savehist-mode, save-place-mode, midnight-mode, uniquify
- auto-image-file-mode, display-time-mode, show-paren-mode
- (f)ido-mode, company-mode

It's a slippery slope, but if done carefully one could perhaps add just
a few more things without weighing it down too much.  Taking out the
toggle to disable the menu bar and tool bar would save some space.

> Others has described the out-of-the-box experience of doom Emacs, it
> seems to me that such job is better done by a “distribution” of Emacs
> than by vanilla Emacs. OTHO, vanilla Emacs could add a tiny guide like
> I proposed to more or less improve the life for those who started
> Emacs without reading any tutorial on the internet.

The idea of profiles/custom themes is orthogonal to the guide you are
proposing, IMO.  You could set a profile and then tweak the options it
gives you.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Gregory Heytings via Emacs development discussions.]

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


>
>> I think there are a few configurations that a beginner would want to 
>> change right after he starts Emacs, usually very basic settings. If you 
>> think it’s a good idea, I can go to reddit and ask what people missed 
>> when then started using Emacs for the first few minutes.
>>
>> FWIW, here is a demo of the guide: https://youtu.be/0qMskTAR2aw
>>
>> The demo inserts some configurations into ~/.emacs.d/init.el after 
>> completion.
>
> Such a beginners guide (wizard) is an excellent idea.  And it is great 
> that you actually have code.  Let's see what others think, but I will 
> optimistically add my comments below.
>

It's great indeed, and not very far from what I had in mind.

In screen 1, it would be great (but I don't know if it is possible) to 
allow the user to select a font (among a short set).

In screen 2, I would add evil-mode in the options.  I would add the "C-o = 
find-file" binding to "cua-mode".  I don't think "s (super)" is useful. 
And I would not write "We encourage you to learn the default binding, 
because...", but "We encourage you to reconsider this choice after some 
time, because...".

In screen 3, I would add hl-line, show-paren-mode, which-key, 
column-number-mode, save-place-mode + desktop-save-mode (both with a 
single choice).  I would also add an option to have "(setq 
uniquify-buffer-name-style 'forward) (setq uniquify-min-dir-content 
1024)".  And an option to bind C-x C-b (and another shorter but less 
useful binding, say C-b) to ibuffer.

I would move screen 4 after screen 2.

And I still think that a short "guided tour" would be useful at the end: 
what/where is the minibuffer and what is its purpose, what does the 
mode-line contain, how to find help (here I would list C-h m, C-h p, C-h k 
/ C-h w / C-h a, C-h l, C-h ?), ...

Re: Interactive guide for new users

[Phil Sainty]

On 2020-09-11 20:15, Gregory Heytings via "Emacs development 
discussions." wrote:
> In screen 2, I would add evil-mode in the options.

Viper, perhaps?

Evil is not contributed to Emacs nor is it in GNU ELPA (and with
GitHub claiming 100 contributors, I expect that this is how it's
going to remain).

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Yuan Fu]

> On Sep 11, 2020, at 4:15 AM, Gregory Heytings <ghe@sdf.org> wrote:
> 
> 
>> 
>>> I think there are a few configurations that a beginner would want to change right after he starts Emacs, usually very basic settings. If you think it’s a good idea, I can go to reddit and ask what people missed when then started using Emacs for the first few minutes.
>>> 
>>> FWIW, here is a demo of the guide: https://youtu.be/0qMskTAR2aw
>>> 
>>> The demo inserts some configurations into ~/.emacs.d/init.el after completion.
>> 
>> Such a beginners guide (wizard) is an excellent idea.  And it is great that you actually have code.  Let's see what others think, but I will optimistically add my comments below.
>> 
> 
> It's great indeed, and not very far from what I had in mind.
> 
> In screen 1, it would be great (but I don't know if it is possible) to allow the user to select a font (among a short set).
> 
> In screen 2, I would add evil-mode in the options.  I would add the "C-o = find-file" binding to "cua-mode".  I don't think "s (super)" is useful. And I would not write "We encourage you to learn the default binding, because...", but "We encourage you to reconsider this choice after some time, because...".
> 
> In screen 3, I would add hl-line, show-paren-mode, which-key, column-number-mode, save-place-mode + desktop-save-mode (both with a single choice).  I would also add an option to have "(setq uniquify-buffer-name-style 'forward) (setq uniquify-min-dir-content 1024)".  And an option to bind C-x C-b (and another shorter but less useful binding, say C-b) to ibuffer.
> 
> I would move screen 4 after screen 2.
> 
> And I still think that a short "guided tour" would be useful at the end: what/where is the minibuffer and what is its purpose, what does the mode-line contain, how to find help (here I would list C-h m, C-h p, C-h k / C-h w / C-h a, C-h l, C-h ?), …

I agree, the current tutorial is a bit verbose (not that I didn’t read it when I started using Emacs, but…). A shorter tutorial introducing the most important bindings and operations would be helpful (I imagine).

Yuan

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Gregory Heytings via Emacs development discussions.]

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


>
>> And I still think that a short "guided tour" would be useful at the 
>> end: what/where is the minibuffer and what is its purpose, what does 
>> the mode-line contain, how to find help (here I would list C-h m, C-h 
>> p, C-h k / C-h w / C-h a, C-h l, C-h ?), …
>
> I agree, the current tutorial is a bit verbose (not that I didn’t read 
> it when I started using Emacs, but…). A shorter tutorial introducing the 
> most important bindings and operations would be helpful (I imagine).
>

It should not just be "shorter", it should be *really* short.  I've just 
read it again, for a new user it is almost useless.  I think the following 
two keybindings would suffice: "C-x 1" and "C-g".  And perhaps the four 
following ones to give the new user a sense of what using C-<something> 
and M-<something> is: "M-f and M-b", "C-a and C-e".  Note that these four 
keybindings are also on M-left and M-right and home and end, which is what 
a new user would use (and it would work).

I would perhaps also add "M-%", which is very useful and not documented in 
the tutorial.

All this could be done in two screens I think.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eli Zaretskii]

> Date: Fri, 11 Sep 2020 14:38:22 +0000
> cc: emacs-devel <emacs-devel@gnu.org>
> From: Gregory Heytings via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> It should not just be "shorter", it should be *really* short.  I've just 
> read it again, for a new user it is almost useless.  I think the following 
> two keybindings would suffice: "C-x 1" and "C-g".  And perhaps the four 
> following ones to give the new user a sense of what using C-<something> 
> and M-<something> is: "M-f and M-b", "C-a and C-e".  Note that these four 
> keybindings are also on M-left and M-right and home and end, which is what 
> a new user would use (and it would work).
> 
> I would perhaps also add "M-%", which is very useful and not documented in 
> the tutorial.

But the tutorial is not just about keybindings.  It explains a lot of
other turf, mainly the important concepts: buffer, window, mode line,
etc.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Gregory Heytings via Emacs development discussions.]

>> It should not just be "shorter", it should be *really* short.  I've 
>> just read it again, for a new user it is almost useless.  I think the 
>> following two keybindings would suffice: "C-x 1" and "C-g".  And 
>> perhaps the four following ones to give the new user a sense of what 
>> using C-<something> and M-<something> is: "M-f and M-b", "C-a and C-e". 
>> Note that these four keybindings are also on M-left and M-right and 
>> home and end, which is what a new user would use (and it would work).
>>
>> I would perhaps also add "M-%", which is very useful and not documented 
>> in the tutorial.
>
> But the tutorial is not just about keybindings.  It explains a lot of 
> other turf, mainly the important concepts: buffer, window, mode line, 
> etc.
>

A new user does not need to understand those subtleties.  He already has 
an intuitive notion of what a buffer and a window are, which suffices to 
start using Emacs.  It is enough to tell him that the mode-line contains 
the name of the major mode followed by minor modes, and that he can have a 
description of those modes and their bindings by pressing "C-h m".

BTW, there is another option that I would add in screen 3: tab-line-mode.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eli Zaretskii]

> Date: Fri, 11 Sep 2020 15:20:18 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> > But the tutorial is not just about keybindings.  It explains a lot of 
> > other turf, mainly the important concepts: buffer, window, mode line, 
> > etc.
> >
> 
> A new user does not need to understand those subtleties.

I wouldn't call these basics "subtleties".  They are the most
fundamental terminology in Emacs.

> He already has an intuitive notion of what a buffer and a window
> are, which suffices to start using Emacs.

He does?  Where from?  Windows mean something else in the other apps,
and buffers are not available in most of them.

> BTW, there is another option that I would add in screen 3: tab-line-mode.

Is the tab-line really such an important feature?  If so, why isn't it
turned on by default?

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Gregory Heytings via Emacs development discussions.]

>>> But the tutorial is not just about keybindings.  It explains a lot of 
>>> other turf, mainly the important concepts: buffer, window, mode line, 
>>> etc.
>>
>> A new user does not need to understand those subtleties.
>
> I wouldn't call these basics "subtleties".  They are the most 
> fundamental terminology in Emacs.
>

They are indeed, I'm not denying this.  My point of view here is: what are 
the most essential things that a user needs to know to use Emacs if we 
have no more than three minutes?  Clearly (at least to me) it is possible 
to use Emacs without knowing what a "buffer" or a "window" is.

>
>> He already has an intuitive notion of what a buffer and a window are, 
>> which suffices to start using Emacs.
>
> He does?  Where from?  Windows mean something else in the other apps, 
> and buffers are not available in most of them.
>

Indeed "window" mean something else for other apps, but why is this 
important for a new user who just wants to edit files?  There are other 
apps in which the screen is splitted in different areas, so he would not 
be surprised when this happens.  And "buffers" are of course available in 
many apps, in most office suites (and text editors) you can just create a 
file with "new" and it's "something that does not correspond to a file 
(yet)".

>
>> BTW, there is another option that I would add in screen 3: 
>> tab-line-mode.
>
> Is the tab-line really such an important feature?  If so, why isn't it 
> turned on by default?
>

I'm not saying that tab-line is an important feature.  It's not an 
important feature for you or me, but it's common in many apps (web 
browsers, text editors) to have a tab-line on which one can click to 
navigate between "buffers".

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eli Zaretskii]

> Date: Fri, 11 Sep 2020 15:46:14 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> > I wouldn't call these basics "subtleties".  They are the most 
> > fundamental terminology in Emacs.
> 
> They are indeed, I'm not denying this.  My point of view here is: what are 
> the most essential things that a user needs to know to use Emacs if we 
> have no more than three minutes?  Clearly (at least to me) it is possible 
> to use Emacs without knowing what a "buffer" or a "window" is.

How would they even understand the doc strings without knowing what's
a buffer and what's a window?  We have the Glossary section in the
manual, for that very reason.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Gregory Heytings via Emacs development discussions.]

>>> I wouldn't call these basics "subtleties".  They are the most 
>>> fundamental terminology in Emacs.
>>
>> They are indeed, I'm not denying this.  My point of view here is: what 
>> are the most essential things that a user needs to know to use Emacs if 
>> we have no more than three minutes?  Clearly (at least to me) it is 
>> possible to use Emacs without knowing what a "buffer" or a "window" is.
>
> How would they even understand the doc strings without knowing what's a 
> buffer and what's a window?  We have the Glossary section in the manual, 
> for that very reason.
>

Again my point of view is: what are the most essential things that a user 
needs to know to use Emacs if we have no more than three minutes?  The 
point is to create a minimal configuration wizard / guided tour to 
introduce them to the most essential things and help them to create a 
minimal configuration with which they would feel "at home", instead of 
having the "this is weird" feeling.

You mention "doc strings", but why on earth would a user who just started 
using Emacs read doc strings?

Re: Interactive guide for new users

[Robert Pluim]

>>>>> On Fri, 11 Sep 2020 16:00:41 +0000, Gregory Heytings via "Emacs development discussions." <emacs-devel@gnu.org> said:

    Emacs> You mention "doc strings", but why on earth would a user who just
    Emacs> started using Emacs read doc strings?

How are we to get them to grow as Emacs users if they donʼt learn how
to learn about Emacs? There are far too many posts on
reddit/stackexchange etc which are easily solved by just reading the
bundled manuals/docstrings.

Robert

Re: Interactive guide for new users

[Emanuel Berg via Emacs development discussions.]

Robert Pluim wrote:

> How are we to get them to grow as Emacs users if
> they don't learn how to learn about Emacs?
> There are far too many posts on
> reddit/stackexchange etc which are easily solved by
> just reading the bundled manuals/docstrings.

The more Emacs posts on Reddit/SX the better.
That and they are part of us as much as
gmane.emacs.devel .

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Interactive guide for new users

[Robert Pluim]

>>>>> On Fri, 11 Sep 2020 19:23:35 +0200, Emanuel Berg via "Emacs development discussions." <emacs-devel@gnu.org> said:

    Emacs> Robert Pluim wrote:
    >> How are we to get them to grow as Emacs users if
    >> they don't learn how to learn about Emacs?
    >> There are far too many posts on
    >> reddit/stackexchange etc which are easily solved by
    >> just reading the bundled manuals/docstrings.

    Emacs> The more Emacs posts on Reddit/SX the better.
    Emacs> That and they are part of us as much as
    Emacs> gmane.emacs.devel .

The more *useful* posts on those the better. Stuff that can be
answered easily by the OP if they know where to look wastes everyone's
time.

Robert

Re: Interactive guide for new users

[Emanuel Berg via Emacs development discussions.]

Robert Pluim wrote:

> The more *useful* posts on those the better.
> Stuff that can be answered easily by the OP if they
> know where to look wastes everyone's time.

No.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eli Zaretskii]

> Date: Fri, 11 Sep 2020 16:00:41 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> > How would they even understand the doc strings without knowing what's a 
> > buffer and what's a window?  We have the Glossary section in the manual, 
> > for that very reason.
> 
> Again my point of view is: what are the most essential things that a user 
> needs to know to use Emacs if we have no more than three minutes?  The 
> point is to create a minimal configuration wizard / guided tour to 
> introduce them to the most essential things and help them to create a 
> minimal configuration with which they would feel "at home", instead of 
> having the "this is weird" feeling.

That is a very different goal from that of our tutorial (or any good
tutorial, IMO).  A tutorial should present the important workings of
the tool it describes, which includes all the basic operations and
ideas.

A user who has no more than 3 minutes can just start typing and use
the menus for the rest.  I believe Emacs supports all the features
such a user can expect: cursor motion with arrows and PageUp/PageDown,
text insertion and deletion, saving via the menus, etc.

But if you think such "3-minute users" need a document to get them
started, by all means, write such a document.  It is not what the
tutorial attempts to do, though.

> You mention "doc strings", but why on earth would a user who just started 
> using Emacs read doc strings?

To learn more about Emacs, of course.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Ergus]

On Fri, Sep 11, 2020 at 09:43:09PM +0300, Eli Zaretskii wrote:
>> Date: Fri, 11 Sep 2020 16:00:41 +0000
>> From: Gregory Heytings <ghe@sdf.org>
>> cc: casouri@gmail.com, emacs-devel@gnu.org
>>
>> > How would they even understand the doc strings without knowing what's a
>> > buffer and what's a window?  We have the Glossary section in the manual,
>> > for that very reason.
>>
>> Again my point of view is: what are the most essential things that a user
>> needs to know to use Emacs if we have no more than three minutes?  The
>> point is to create a minimal configuration wizard / guided tour to
>> introduce them to the most essential things and help them to create a
>> minimal configuration with which they would feel "at home", instead of
>> having the "this is weird" feeling.
>
>That is a very different goal from that of our tutorial (or any good
>tutorial, IMO).  A tutorial should present the important workings of
>the tool it describes, which includes all the basic operations and
>ideas.
>
>A user who has no more than 3 minutes can just start typing and use
>the menus for the rest.  I believe Emacs supports all the features
>such a user can expect: cursor motion with arrows and PageUp/PageDown,
>text insertion and deletion, saving via the menus, etc.
>
>But if you think such "3-minute users" need a document to get them
>started, by all means, write such a document.  It is not what the
>tutorial attempts to do, though.
>

Lets say that the problem is the unfamiliar way how emacs work in some
aspects. In this list is repeated constantly that we shouldn't do this
or that; or use a such set of bindings, colors, or methods just because
the other editors do. So the only way to keep that is enforcing a
learning curve because very little users will arrive trained in "the
emacs way".

If a user opens any editor around he never looks into the menus for copy
or paste, but just right-click and a panel or C-c and C-v as they are
standard anywhere else.

I don't like to enable CUA mode by default, but start emacs and work is
not so easy so if a user only have 3 minutes to start he will open
gedit, kwire, kate or geany and everything works as expected in those 3
minutes.

>> You mention "doc strings", but why on earth would a user who just started
>> using Emacs read doc strings?
>
>To learn more about Emacs, of course.
>

I said that, 5-10 minutes is a bit better than 3. IMO the Mike's videos
are the perfect format. Maybe the only problem is the emacs window size
on the screen and that they are more oriented to the external packages
than in the internals.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eli Zaretskii]

> Date: Fri, 11 Sep 2020 21:48:52 +0200
> From: Ergus <spacibba@aol.com>
> Cc: Gregory Heytings <ghe@sdf.org>, casouri@gmail.com, emacs-devel@gnu.org
> 
> >But if you think such "3-minute users" need a document to get them
> >started, by all means, write such a document.  It is not what the
> >tutorial attempts to do, though.
> >
> 
> Lets say that the problem is the unfamiliar way how emacs work in some
> aspects.

Like what? please be more specific, otherwise it's very hard to
understand what you have in mind.

> In this list is repeated constantly that we shouldn't do this
> or that; or use a such set of bindings, colors, or methods just because
> the other editors do. So the only way to keep that is enforcing a
> learning curve because very little users will arrive trained in "the
> emacs way".

Once again: most basic things people expect from an editor "just work"
in Emacs OOTB.

> If a user opens any editor around he never looks into the menus for copy
> or paste, but just right-click and a panel or C-c and C-v as they are
> standard anywhere else.

So this is about CUA-like key bindings? or is there anything else?

> I don't like to enable CUA mode by default, but start emacs and work is
> not so easy so if a user only have 3 minutes to start he will open
> gedit, kwire, kate or geany and everything works as expected in those 3
> minutes.

Fine, then I guess this is what the "3-minute tutorial" should say.

> >> You mention "doc strings", but why on earth would a user who just started
> >> using Emacs read doc strings?
> >
> >To learn more about Emacs, of course.
> >
> 
> I said that, 5-10 minutes is a bit better than 3. IMO the Mike's videos
> are the perfect format. Maybe the only problem is the emacs window size
> on the screen and that they are more oriented to the external packages
> than in the internals.

To have video tutorials for these purposes is perfectly okay.  I hope
we will be able to have them soon.

Thanks.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Ergus]

On September 12, 2020 8:02:55 AM GMT+02:00, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, 11 Sep 2020 21:48:52 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: Gregory Heytings <ghe@sdf.org>, casouri@gmail.com,
>emacs-devel@gnu.org
>> 
>> >But if you think such "3-minute users" need a document to get them
>> >started, by all means, write such a document.  It is not what the
>> >tutorial attempts to do, though.
>> >
>> 
>> Lets say that the problem is the unfamiliar way how emacs work in
>some
>> aspects.
>
>Like what? please be more specific, otherwise it's very hard to
>understand what you have in mind.
>
Like right click panel and cua. I don't like any of those, but my point is that in 3 minutes is hard to face that none of them are there as expected.

>> In this list is repeated constantly that we shouldn't do this
>> or that; or use a such set of bindings, colors, or methods just
>because
>> the other editors do. So the only way to keep that is enforcing a
>> learning curve because very little users will arrive trained in "the
>> emacs way".
>
>Once again: most basic things people expect from an editor "just work"
>in Emacs OOTB.
>
>> If a user opens any editor around he never looks into the menus for
>copy
>> or paste, but just right-click and a panel or C-c and C-v as they are
>> standard anywhere else.
>
>So this is about CUA-like key bindings?

I just said explicitly that I don't like Cua mode. Even when M-w and the others are not really better IMO.

> or is there anything else?

The very usefull right click panel.

>
>> I don't like to enable CUA mode by default, but start emacs and work
>is
>> not so easy so if a user only have 3 minutes to start he will open
>> gedit, kwire, kate or geany and everything works as expected in those
>3
>> minutes.
>
>Fine, then I guess this is what the "3-minute tutorial" should say.
>
IMO we should focus in at least 5-10 minutes users more than 3 minutes ones. Because to focus in the 3 minutes ones emacs will require at least a permanent visible bindings bar somewhere (like nano) or change many things to make them familiar for external users. And we won't do that I think :/

>> >> You mention "doc strings", but why on earth would a user who just
>started
>> >> using Emacs read doc strings?
>> >
>> >To learn more about Emacs, of course.
>> >
>> 
>> I said that, 5-10 minutes is a bit better than 3. IMO the Mike's
>videos
>> are the perfect format. Maybe the only problem is the emacs window
>size
>> on the screen and that they are more oriented to the external
>packages
>> than in the internals.
>
>To have video tutorials for these purposes is perfectly okay.  I hope
>we will be able to have them soon.
>
>Thanks.

Have you seen any of the mike's videos? IMO they are already useful for new users. Let's hope he port them to peertube.
-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: Interactive guide for new users

[Philip K.]

Ergus <spacibba@aol.com> writes:

> IMO we should focus in at least 5-10 minutes users more than 3 minutes
> ones. Because to focus in the 3 minutes ones emacs will require at
> least a permanent visible bindings bar somewhere (like nano) or change
> many things to make them familiar for external users. And we won't do
> that I think :/

Why does that follow? And even so, if you have a video on "moving text",
"help system basics" or "managing buffers", you're going to handle 3-4
keybindings and their functions at most, and that's something that could
already be pasted into the scratch buffer (or some other buffer) to
begin with.

-- 
	Philip K.

FW: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Drew Adams]

[Was bitten by the Reply All misses emacs-devel thing again...]

>> But the tutorial is not just about keybindings.  It explains a lot of 
>> other turf, mainly the important concepts: buffer, window, mode line, 
>> etc.
>
> A new user does not need to understand those subtleties.

See below.  You seemed earlier to say that such things as
the mode-line are essential for a new user to understand.

> >> They are indeed, I'm not denying this.  My point of view here is: what
> >> are the most essential things that a user needs to know to use Emacs if
> >> we have no more than three minutes?  Clearly (at least to me) it is
> >> possible to use Emacs without knowing what a "buffer" or a "window" is.
> >
> > How would they even understand the doc strings without knowing what's a
> > buffer and what's a window?  We have the Glossary section in the manual,
> > for that very reason.
> 
> Again my point of view is: what are the most essential things that a user
> needs to know to use Emacs if we have no more than three minutes?  The
> point is to create a minimal configuration wizard / guided tour to
> introduce them to the most essential things and help them to create a
> minimal configuration with which they would feel "at home", instead of
> having the "this is weird" feeling.

The "most essential things" are not cursor movements.
The arrow keys, familiar to all, suffice for that,
to begin with.

> You mention "doc strings", but why on earth would
> a user who just started using Emacs read doc strings?

The most essential thing, if you really expect something
in less than 3 minutes, is _how to ask Emacs_, so that
you can learn more when you need/want to.

And yes, that starts with help commands, which means
doc strings.

C-h C-h, if nothing else.

Then C-h k, C-h m, C-h v, C-h f, C-h i,...

And you, yourself, said something similar earlier:

> And I still think that a short "guided tour" would be
> useful at the end: what/where is the minibuffer and
> what is its purpose, what does the 
> mode-line contain, how to find help (here I would list
> C-h m, C-h p, C-h k / C-h w / C-h a, C-h l, C-h ?), ...

And there you also seem to support what Eli says about
the need to introduce fundamental concepts - Emacs things.
You mention the minibuffer and the mode-line.  He mentions
buffers, windows, etc.

ALL of that is needed: basic Emacs thingies + how to ask Emacs.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Göktuğ Kayaalp]

On 2020-09-11 18:46 +03, Gregory Heytings via Emacs development discussions. <emacs-devel@gnu.org> wrote:
> They are indeed, I'm not denying this.  My point of view here is: what
> are the most essential things that a user needs to know to use Emacs
> if we have no more than three minutes?  Clearly (at least to me) it is
> possible to use Emacs without knowing what a "buffer" or a "window"
> is.

Someone who can’t spare more than three minutes to research a tool that
they may end up using for a life time for the majority of their workday
is IMHO not a kind of user we should strive to support.


--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Emanuel Berg via Emacs development discussions.]

G Kayaalp wrote:

> Someone who can’t spare more than three minutes to
> research a tool that they may end up using for
> a life time for the majority of their workday is
> IMHO not a kind of user we should strive
> to support.

ikr?

Because they are not worthy!

"Better Fewer, But Better" [1] Great essay by old
Vladimir Ilyich.

Hey, worked for him so why not for us?


[1] https://www.marxists.org/archive/lenin/works/1923/mar/02.htm

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Praharsh Suryadevara]

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

On Fri, Sep 11, 2020 at 12:48 PM Göktuğ Kayaalp <self@gkayaalp.com> wrote:

> On 2020-09-11 18:46 +03, Gregory Heytings via Emacs development
> discussions. <emacs-devel@gnu.org> wrote:
> > They are indeed, I'm not denying this.  My point of view here is: what
> > are the most essential things that a user needs to know to use Emacs
> > if we have no more than three minutes?  Clearly (at least to me) it is
> > possible to use Emacs without knowing what a "buffer" or a "window"
> > is.
>
> Someone who can’t spare more than three minutes to research a tool that
> they may end up using for a life time for the majority of their workday
> is IMHO not a kind of user we should strive to support.
>

I think it would be valuable, IMO there's too much unsaid for first-time
users and there's important info that can get lost (like CUA mode),
it wouldn't help if they missed it. It helps to save people's time in the
beginning, even if they know emacs may save them time later on.

Time is valuable.





>
>
> --
> İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
> pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427
>
>

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

Re: Interactive guide for new users

[Lars Ingebrigtsen]

Göktuğ Kayaalp <self@gkayaalp.com> writes:

> Someone who can’t spare more than three minutes to research a tool that
> they may end up using for a life time for the majority of their workday
> is IMHO not a kind of user we should strive to support.

I think that's dangerously close to saying "Emacs was hard to make, so
it should be hard to use".

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Interactive guide for new users

[Göktuğ Kayaalp]

On 2020-09-12 14:16 +03, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> Göktuğ Kayaalp <self@gkayaalp.com> writes:
>> Someone who can’t spare more than three minutes to research a tool that
>> they may end up using for a life time for the majority of their workday
>> is IMHO not a kind of user we should strive to support.
> I think that's dangerously close to saying "Emacs was hard to make, so
> it should be hard to use".

Well, that’s one way to read it.  Another way, which is what I intend,
is that Emacs is a power tool, and some learning curve is inevitable no
matter how easy we make certain things.  And overcoming that requires
some effort.

That of course shouldn’t prevent documenting to the best of our ability
and make sure we’re not wasting nobody’s time, but that should not mean
we should cater to those who are not readily willing to use this piece
of software and are unwilling to put any time into learning enough to
evaluating it.  In a given day we probably spend more than three minutes
just looking into void.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

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


>>> Someone who can’t spare more than three minutes to research a tool 
>>> that they may end up using for a life time for the majority of their 
>>> workday is IMHO not a kind of user we should strive to support.
>>
>> I think that's dangerously close to saying "Emacs was hard to make, so 
>> it should be hard to use".
>
> Well, that’s one way to read it.  Another way, which is what I intend, 
> is that Emacs is a power tool, and some learning curve is inevitable no 
> matter how easy we make certain things.  And overcoming that requires 
> some effort.
>

There are many text editors, most of them are power tools too (not as much 
as Emacs of course, but this is something a new user cannot know or 
evaluate).  Other text editors do not have a learning curve to do simple 
operations like cut, copy and paste, or to choose a color theme.  I don't 
think it's a good thing if the first message you send to a new user is 
"you will suffer" (or "abandon all hope, ye who enter here").  The purpose 
of the current discussion is only to do something to give them a feeling 
of curiosity instead of a feeling of fear.

Re: Interactive guide for new users

[Göktuğ Kayaalp]

On 2020-09-12 17:55 +03, Gregory Heytings <ghe@sdf.org> wrote:
>  I don't think it's a good thing if the first message you send to a
> new user is "you will suffer" (or "abandon all hope, ye who enter
> here").

I don’t get why you equate ‘effort’ with ‘suffering’.  That’s a reductio
ad absurdum, and pretty far off from "this thing here is something
that’ll pay you back with great rewards once you decide to invest some
time into learning it".

>  The purpose of the current discussion is only to do something to give
> them a feeling of curiosity instead of a feeling of fear.

Which is not something I disagree with.  All I’m saying is that a user
who has no interest in Emacs should not be how we’re designing for.
Because that limits what you can achieve.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

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


>> The purpose of the current discussion is only to do something to give 
>> them a feeling of curiosity instead of a feeling of fear.
>
> Which is not something I disagree with.  All I’m saying is that a user 
> who has no interest in Emacs should not be how we’re designing for. 
> Because that limits what you can achieve.
>

What I'm saying is that a user who does not know Emacs is initially 
neither interested nor desinterested.  They just start a text editor. 
The purpose of this guided tour is precisely to make them interested.

If the first feeling they have is fear, the become disinterested (or at 
least are more likely to become disinterested).  If the first feeling they 
have is curiosity, they become interested (or at least are more likely to 
become interested).

Re: Interactive guide for new users

[Juri Linkov]

> It should not just be "shorter", it should be *really* short.  I've just
> read it again, for a new user it is almost useless.  I think the following
> two keybindings would suffice: "C-x 1" and "C-g".

Instead of "C-g", it's easier to type the standard ESC key:

  (when window-system
    (define-key global-map [escape] 'keyboard-escape-quit))

I don't suggest to enable this by default, but this could be added
to one of profiles.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Yuan Fu]

> 
> I propose to consider if any of these are suitable for inclusion:
> 
> - scroll-conservatively, visible-bell
> - desktop-save-mode, savehist-mode, save-place-mode, midnight-mode, uniquify
> - auto-image-file-mode, display-time-mode, show-paren-mode
> - (f)ido-mode, company-mode
> 
> It's a slippery slope, but if done carefully one could perhaps add just
> a few more things without weighing it down too much.  Taking out the
> toggle to disable the menu bar and tool bar would save some space.
> 

What I included in the guide is just for example. I was hoping to get some feedback on reddit about the real struggle of beginners. Then we know what they really need.

Yuan

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

Based on the feedback received so far, I reworked the proposal a bit. 
The idea is to create an "initial greeting" that would be bundled with 
Emacs, and would be executed the first time the first time Emacs is 
launched (instead of the initial splash screen).  It should be short (take 
no more than three minutes to go through), and give the user (1) a way to 
set some defaults according to their preferences, and (2) a short 
introduction to the most important elements of Emacs.

The rationale behind this proposal is the discussion that started with 
Ergus' mail a week ago.  It is hard to synthetize what has been said, but 
it seems to me that it boils down to two incompatible viewpoints: (1) 
those who have been using Emacs for years do not want to change the 
default settings too much, and (2) new Emacs users, who already know and 
use other text editors (Visual Studio, Atom, ...), are puzzled with its 
interface and find that it does not look "modern" enough.  IOW, the only 
purpose of this proposal is to do something to avoid the initial feeling 
some users have that Emacs is an old thing that they will have difficulty 
to adapt to their needs.

The initial greeting would have eight screens, which I detail here because 
some on this list prefer not to view videos on Youtube:

SCREEN 1: Welcome!  It seems that this is the first time you run Emacs, 
would you like to customize its interface and have a short introduction? 
This will not take you more than three minutes.

SCREEN 2: "Set the color theme", with a clickable list containing the 
(currently) 16 built-in themes.  A short code snippet above that list 
illustrates how code is displayed with each of these themes.  [It would be 
nice to have a way to select a default font here, but I don't know if that 
feasible.]

SCREEN 3: Basic keybindings.  It introduces the "C-" and "M-" notations, 
and the user can select between the default keybindings and cua-mode (with 
some additional keybindings).  This "enhanced cua-mode" would have: C-c = 
copy, C-v = paste, C-x = cut, C-f = search, C-s = save, C-o = open file, 
C-z = undo, C-y = redo.  If the user selects the cua-mode bindings, he 
gets a message: "We encourage to reconsider this choice after some time, 
because the alternative keybindings conflict with many parts of Emacs and 
make the experience worse in the long run."

SCREEN 4: Choose whether to set some common options that new users might 
want (because they are common in other text editors).  These are (the 
order could be improved, and items could be added or removed):

1. display-line-numbers-mode
2. disable tool-bar-mode
3. disable scroll-bar-mode
4. column-number-mode
5. (setq cursor-type 'bar)
6. hl-line-mode
7. show-paren-mode
8. which-key-mode
9. column-number-mode
10. save-place-mode and desktop-save-mode
11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)
12. tab-line-mode
13. (global-set-key (kbd "C-b") 'ibuffer) [if cua-mode has been chosen]
14. icomplete-mode (or fido-mode?)
15. (setq scroll-conservatively 101)
16. display-time-mode
17. (setq tool-bar-style 'image)

SCREEN 5: Short explanations about what the user sees: the minibuffer 
(where commands are entered and error messages appear), the mode-line 
(with the current editing modes between parentheses, the first one is the 
major mode), with a mention that the user can have a description of these 
modes and of their keybindings by typing "C-h m".

SCREEN 6: How to find help.  Short explanation about C-h C-h, C-h m, C-h 
p, C-h k / C-h w / C-h a, C-h l.  Note on terminology: in the 
documentation two words might be confusing, "frame" is what is generally 
known as "window", and "window" is a portion of a frame when it is 
splitted in two or more parts.  [Also explain what a "buffer"?]

SCREEN 7: Elementary keybindings: explain what "C-x 1" and "C-g" do. 
Give a few examples to give the new user a sense of what using 
C-<something> and M-<something> is:

1. "M-f and M-b" (which have the same effect as M-<left> and M-<right>)
2. "C-a and C-e" (which have the same effect as <home> and <end>)
3. "M-%" and "C-M-%"

SCREEN 8: Thank you. Your choices have been saved in Emacs' configuration 
file ~/.emacs.d/init.el (or ~/.emacs ?).  You can use M-x customize at any 
time to set additional configuration options.  You can use M-x 
initial-greeting at any time to go through this configuration again.

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 09:31:06 +0000
> From: Gregory Heytings via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> 
> Based on the feedback received so far, I reworked the proposal a bit. 

Thanks for thinking about this.  I have a few minor comments.

> The idea is to create an "initial greeting" that would be bundled with 
> Emacs, and would be executed the first time the first time Emacs is 
> launched (instead of the initial splash screen).

What is the definition of "the first time"? where will we keep the
indication that this is/isn't "the first time"?  Also, will this
affect "emacs -Q" or "emacs -q"?

> SCREEN 1: Welcome!  It seems that this is the first time you run Emacs, 
> would you like to customize its interface and have a short introduction? 
> This will not take you more than three minutes.

I presume this will have a button "Not now" and "Don't show this
again" or somesuch?

> SCREEN 2: "Set the color theme", with a clickable list containing the 
> (currently) 16 built-in themes.  A short code snippet above that list 
> illustrates how code is displayed with each of these themes.

The snippet will only be able to show the buffer text appearance.  For
other UI elements you will need an image.  Would using an image be
better here?

> [It would be nice to have a way to select a default font here, but I
> don't know if that feasible.]

I don't think I understand what you mean by that.  Selection of the
default font _is_ possible, we have in the Options menu.

> SCREEN 4: Choose whether to set some common options that new users might 
> want (because they are common in other text editors).  These are (the 
> order could be improved, and items could be added or removed):

We should carefully construct the list of the options, they shouldn't
just be someone's personal preferences.

> 2. disable tool-bar-mode
> 3. disable scroll-bar-mode

I'd object to these two.  We have just established that the former is
important for newbies.  Scroll bars are presented by many
applications, so why is it important to offer to turn them off here?
let the users decide about these two.

> 6. hl-line-mode

Why is this important? do other IDEs have it by default?

> 8. which-key-mode

I disagree with this one, certainly in its current form.

> 10. save-place-mode and desktop-save-mode

desktop-save-mode slows down startup, so it might not be suitable for
users who start Emacs many times a day.

> 11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)

Why? what's wrong with the defaults here?

> 14. icomplete-mode (or fido-mode?)

Not sure this is a good idea, these modes present complex and
potentially confusing UI.

> 16. display-time-mode

Why?  Any modern desktop has the time displayed somewhere, so this
just occupies space on the mode line.

> SCREEN 6: How to find help.  Short explanation about C-h C-h, C-h m, C-h 
> p, C-h k / C-h w / C-h a, C-h l.

This misses important help commands, we should consider the list
carefully with newbies in mind.  IMO, the various apropos commands are
much more important for them than other help commands.

> SCREEN 8: Thank you. Your choices have been saved in Emacs' configuration 
> file ~/.emacs.d/init.el (or ~/.emacs ?).

What do we do here wrt XDG preferences?

> You can use M-x initial-greeting at any time to go through this
> configuration again.

That command should be on the Help menu.  And I think the name should
be 'introduction-to-emacs' or somesuch.

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

Hi Eli,

Thanks for your feedback.  Some comments below.

>
>> The idea is to create an "initial greeting" that would be bundled with 
>> Emacs, and would be executed the first time the first time Emacs is 
>> launched (instead of the initial splash screen).
>
> What is the definition of "the first time"? where will we keep the 
> indication that this is/isn't "the first time"?  Also, will this affect 
> "emacs -Q" or "emacs -q"?
>

What I had in mind is something like "if -Q is not present and -q is not 
present and .emacs does not exist and ~/.emacs.d does not exit".

>
>> SCREEN 1: Welcome!  It seems that this is the first time you run Emacs, 
>> would you like to customize its interface and have a short 
>> introduction? This will not take you more than three minutes.
>
> I presume this will have a button "Not now" and "Don't show this again" 
> or somesuch?
>

Yes.  Clicking on either of these buttons would show the splash screen. 
"Not now" would not do anything, so the initial greeting would be executed 
again the next time Emacs is started.  And "Don't show this again" would 
create an empty ~/.emacs / ~/.emacs.d/init.el, so the initial greeting 
would not be executed again.

>
>> SCREEN 2: "Set the color theme", with a clickable list containing the 
>> (currently) 16 built-in themes.  A short code snippet above that list 
>> illustrates how code is displayed with each of these themes.
>
> The snippet will only be able to show the buffer text appearance.  For 
> other UI elements you will need an image.  Would using an image be 
> better here?
>

What do you mean by "other UI elements"?

>
>> [It would be nice to have a way to select a default font here, but I 
>> don't know if that feasible.]
>
> I don't think I understand what you mean by that.  Selection of the 
> default font _is_ possible, we have in the Options menu.
>

Yes, but what I meant is to have a list of font names in the buffer, and 
choosing a font by clicking on the font name.

>
>> SCREEN 4: Choose whether to set some common options that new users 
>> might want (because they are common in other text editors).  These are 
>> (the order could be improved, and items could be added or removed):
>
> We should carefully construct the list of the options, they shouldn't 
> just be someone's personal preferences.
>

Yes, of course.  That's one of the the purposes of my email.

>
>> 2. disable tool-bar-mode
>> 3. disable scroll-bar-mode
>
> I'd object to these two.  We have just established that the former is 
> important for newbies.  Scroll bars are presented by many applications, 
> so why is it important to offer to turn them off here? let the users 
> decide about these two.
>

It's just an option.  In the video by Yuan Fu ( 
https://youtu.be/0qMskTAR2aw ) you'll see that this screen is a list of 
checkboxes that the user can tick.

>
>> 6. hl-line-mode
>
> Why is this important? do other IDEs have it by default?
>

Yes.  Perhaps not all of them, but it's a very common thing.

>
>> 8. which-key-mode
>
> I disagree with this one, certainly in its current form.
>

Okay.

>
>> 10. save-place-mode and desktop-save-mode
>
> desktop-save-mode slows down startup, so it might not be suitable for 
> users who start Emacs many times a day.
>

Again it's just an option, but again it's someting that users might want 
to enable because it's a behavior that is common in text editors.

>
>> 11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)
>
> Why? what's wrong with the defaults here?
>

This has been discussed earlier in another thread, but the current 
defaults (uniquify-buffer-name-style set to post-forward-angle-brackets) 
is puzzling to most users, to say the least.  A complete file name is what 
most users would expect here.

>
>> 14. icomplete-mode (or fido-mode?)
>
> Not sure this is a good idea, these modes present complex and 
> potentially confusing UI.
>

Users expect to see completion mechanisms in a modern editor.  Enabling 
completion in programming modes would be a too complex task for such an 
initial greeting, but with this the user would become aware that 
completion mechanisms exist in Emacs.

I use icomplete-mode myself, and don't understand what you mean by 
"complex and potentially confusing UI".

>
>> 16. display-time-mode
>
> Why?  Any modern desktop has the time displayed somewhere, so this just 
> occupies space on the mode line.
>

Again it's just an option.  One benefit of adding this in the list is that 
a user who would try it would see that the mode-line can be customized.

>
>> SCREEN 6: How to find help.  Short explanation about C-h C-h, C-h m, 
>> C-h p, C-h k / C-h w / C-h a, C-h l.
>
> This misses important help commands, we should consider the list 
> carefully with newbies in mind.  IMO, the various apropos commands are 
> much more important for them than other help commands.
>

Well, C-h C-h gives the complete list, and C-h a starts apropos.

BTW, on a second thought I would add a mention of "C-h e" in screen 5 
(when the minibuffer is introduced), and repeat it in screen 6.

>
>> SCREEN 8: Thank you. Your choices have been saved in Emacs' 
>> configuration file ~/.emacs.d/init.el (or ~/.emacs ?).
>
> What do we do here wrt XDG preferences?
>

This I don't know.

>
>> You can use M-x initial-greeting at any time to go through this 
>> configuration again.
>
> That command should be on the Help menu.  And I think the name should be 
> 'introduction-to-emacs' or somesuch.
>

Okay, that's fine for me.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 10:35:06AM +0000, Gregory Heytings via Emacs development discussions. wrote:

>>>11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)
>>
>>Why? what's wrong with the defaults here?
>>
>
>This has been discussed earlier in another thread, but the current 
>defaults (uniquify-buffer-name-style set to 
>post-forward-angle-brackets) is puzzling to most users, to say the 
>least.  A complete file name is what most users would expect here.
>
Indeed!! I didn't know about this option.. Setting it right now!!!

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 10:35:06 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> >> SCREEN 2: "Set the color theme", with a clickable list containing the 
> >> (currently) 16 built-in themes.  A short code snippet above that list 
> >> illustrates how code is displayed with each of these themes.
> >
> > The snippet will only be able to show the buffer text appearance.  For 
> > other UI elements you will need an image.  Would using an image be 
> > better here?
> 
> What do you mean by "other UI elements"?

The mode line, the scroll bars, the menu and the tool bar.

> >> [It would be nice to have a way to select a default font here, but I 
> >> don't know if that feasible.]
> >
> > I don't think I understand what you mean by that.  Selection of the 
> > default font _is_ possible, we have in the Options menu.
> 
> Yes, but what I meant is to have a list of font names in the buffer, and 
> choosing a font by clicking on the font name.

Why?  The Options menu item I've mentioned pops up the system's font
selection dialog, which is way nicer than selecting a font from an
Emacs buffer.  To say nothing of being less work.  What am I missing?

> >> 2. disable tool-bar-mode
> >> 3. disable scroll-bar-mode
> >
> > I'd object to these two.  We have just established that the former is 
> > important for newbies.  Scroll bars are presented by many applications, 
> > so why is it important to offer to turn them off here? let the users 
> > decide about these two.
> >
> 
> It's just an option.  In the video by Yuan Fu ( 
> https://youtu.be/0qMskTAR2aw ) you'll see that this screen is a list of 
> checkboxes that the user can tick.

My point is that we should not put there unimportant options, let
alone those which we recommend not to change from the defaults.

> >> 10. save-place-mode and desktop-save-mode
> >
> > desktop-save-mode slows down startup, so it might not be suitable for 
> > users who start Emacs many times a day.
> >
> 
> Again it's just an option, but again it's someting that users might want 
> to enable because it's a behavior that is common in text editors.

There are thousands of options in Emacs that users might want to
enable.  This initial guide should only show those which are very
important, recommended, and usually expected.  Options that don't
satisfy these criteria should IMO not be in the list, because the list
must not be too long, or you will lose many newbies who don't have
enough patience.

> >> 11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)
> >
> > Why? what's wrong with the defaults here?
> >
> 
> This has been discussed earlier in another thread, but the current 
> defaults (uniquify-buffer-name-style set to post-forward-angle-brackets) 
> is puzzling to most users, to say the least.  A complete file name is what 
> most users would expect here.

A complete file name takes too much of the screen space on the mode
line, IMO.  You'd need to make the font used by the mode-line face to
be much smaller, and even then it will steal too much space.

> >> 14. icomplete-mode (or fido-mode?)
> >
> > Not sure this is a good idea, these modes present complex and 
> > potentially confusing UI.
> >
> 
> Users expect to see completion mechanisms in a modern editor.  Enabling 
> completion in programming modes would be a too complex task for such an 
> initial greeting, but with this the user would become aware that 
> completion mechanisms exist in Emacs.

Then perhaps we need to develop a new completion mechanism.  Which
IDEs show completion like icomplete-mode?

> I use icomplete-mode myself, and don't understand what you mean by 
> "complex and potentially confusing UI".

Type "C-x C-f" and try to look at the result with the newbies' eyes.
First question I have is "how to go on?"  <RIGHT> arrow doesn't work.
If the font shows the bold letters distinct enough, I'd wonder what do
the bold letters mean.  The order in which the files are shown doesn't
necessarily make sense, nor does the fact that it mixes directories
with files.  Etc. etc. -- the stuff I'd wonder about goes on and on.
This is not the completion I find, e.g., in a Web browser, so prior
experience will not help.

> >> SCREEN 6: How to find help.  Short explanation about C-h C-h, C-h m, 
> >> C-h p, C-h k / C-h w / C-h a, C-h l.
> >
> > This misses important help commands, we should consider the list 
> > carefully with newbies in mind.  IMO, the various apropos commands are 
> > much more important for them than other help commands.
> >
> 
> Well, C-h C-h gives the complete list, and C-h a starts apropos.

There are several apropos commands, and they are all very important
for discoverability.

Re: Interactive guide for new users

[Dmitry Gutov]

On 12.09.2020 13:58, Eli Zaretskii wrote:
>>>> 11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)
>>> Why? what's wrong with the defaults here?
>>>
>> This has been discussed earlier in another thread, but the current
>> defaults (uniquify-buffer-name-style set to post-forward-angle-brackets)
>> is puzzling to most users, to say the least.  A complete file name is what
>> most users would expect here.
> A complete file name takes too much of the screen space on the mode
> line, IMO.  You'd need to make the font used by the mode-line face to
> be much smaller, and even then it will steal too much space.

This value of uniquify-buffer-name-style has been a part of every major 
"starter kit" for quite some time:

https://github.com/bbatsov/prelude/blob/dd9b01a991c9599842ba88e52fe6ae8627f4a782/core/prelude-editor.el#L105

https://github.com/hlissner/doom-emacs/blob/a2a5038b970df20ec512447b7bbbe96fa2446851/core/core-ui.el#L166

https://git.sr.ht/~technomancy/better-defaults/tree/master/better-defaults.el#L63

So we can say for sure that people find it comfortable enough.

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

>>> The snippet will only be able to show the buffer text appearance. 
>>> For other UI elements you will need an image.  Would using an image be 
>>> better here?
>>
>> What do you mean by "other UI elements"?
>
> The mode line, the scroll bars, the menu and the tool bar.
>

The effect on the mode line is show on the fly, see the video Yuan Fu 
made.  For the scroll bars, the menu and the tool bar, I don't know if it 
is possible to change their appearance within Emacs.  Is it possible?

>>>>> [It would be nice to have a way to select a default font here, but I
>>>> don't know if that feasible.]
>>>
>>> I don't think I understand what you mean by that.  Selection of the 
>>> default font _is_ possible, we have in the Options menu.
>>
>> Yes, but what I meant is to have a list of font names in the buffer, 
>> and choosing a font by clicking on the font name.
>
> Why?  The Options menu item I've mentioned pops up the system's font 
> selection dialog, which is way nicer than selecting a font from an Emacs 
> buffer.  To say nothing of being less work.  What am I missing?
>

You're not missing anything.  It's just convenience for new users, telling 
them to go there and there to do this and that is more confusing than 
offering them a limited number of options during the guided tour.

But if that's too complex to do, this part should be skipped.

>>>> 2. disable tool-bar-mode
>>>> 3. disable scroll-bar-mode
>>>
>>> I'd object to these two.  We have just established that the former is 
>>> important for newbies.  Scroll bars are presented by many 
>>> applications, so why is it important to offer to turn them off here? 
>>> let the users decide about these two.
>>
>> It's just an option.  In the video by Yuan Fu ( 
>> https://youtu.be/0qMskTAR2aw ) you'll see that this screen is a list of 
>> checkboxes that the user can tick.
>
> My point is that we should not put there unimportant options, let alone 
> those which we recommend not to change from the defaults.
>

I think the criterion here is not whether an option is from our point of 
view important or unimportant, or whether we recommend or not to change 
its default value, but whether a user coming from another editing 
environment is likely to want it to feel "at home".  If Doom Emacs, 
Spacemacs and the like disable the tool bar and the scroll bar, that's an 
indication that it's something new users might want.  Note that I did not 
(on purpose) include menu-bar-mode here.

>
> There are thousands of options in Emacs that users might want to enable. 
> This initial guide should only show those which are very important, 
> recommended, and usually expected.  Options that don't satisfy these 
> criteria should IMO not be in the list, because the list must not be too 
> long, or you will lose many newbies who don't have enough patience.
>

See above.  I agree with "usually expected", but "very important" or 
"recommended" is from my point of view too difficult to judge.

>>>> 11. (setq uniquify-buffer-name-style 'forward 
>>>> uniquify-min-dir-content 1024)
>>>
>>> Why? what's wrong with the defaults here?
>>>
>>
>> This has been discussed earlier in another thread, but the current 
>> defaults (uniquify-buffer-name-style set to 
>> post-forward-angle-brackets) is puzzling to most users, to say the 
>> least.  A complete file name is what most users would expect here.
>
> A complete file name takes too much of the screen space on the mode 
> line, IMO.  You'd need to make the font used by the mode-line face to be 
> much smaller, and even then it will steal too much space.
>

That's your point of view, and I agree with you to some extent.  OTOH 
there are not so many available options, and clearly the current default 
(only the filename) is not what users coming from another editor would 
expect.

>
>> I use icomplete-mode myself, and don't understand what you mean by 
>> "complex and potentially confusing UI".
>
> Type "C-x C-f" and try to look at the result with the newbies' eyes. 
> First question I have is "how to go on?"  <RIGHT> arrow doesn't work. If 
> the font shows the bold letters distinct enough, I'd wonder what do the 
> bold letters mean.  The order in which the files are shown doesn't 
> necessarily make sense, nor does the fact that it mixes directories with 
> files.  Etc. etc. -- the stuff I'd wonder about goes on and on. This is 
> not the completion I find, e.g., in a Web browser, so prior experience 
> will not help.
>

I agree with you that with newbies' eyes icomplete could be at first sight 
a bit surprising.  But after typing <right> a user would likely try to 
type something (the cursor is there and blinking) and would quickly 
understand how it works (I think).  If there was a built-in vertical mode 
it would be better / more intuitive.

>>>> SCREEN 6: How to find help.  Short explanation about C-h C-h, C-h m, 
>>>> C-h p, C-h k / C-h w / C-h a, C-h l.
>>>
>>> This misses important help commands, we should consider the list 
>>> carefully with newbies in mind.  IMO, the various apropos commands are 
>>> much more important for them than other help commands.
>>
>> Well, C-h C-h gives the complete list, and C-h a starts apropos.
>
> There are several apropos commands, and they are all very important for 
> discoverability.
>

It's one of the reasons I think offering the user the option to enable 
icomplete makes sense: it helps them to discover options and commands. 
For example M-x apropos lists the individual apropos commands.

That being said, I agree with you that perhaps at this point some of the 
apropos commands could be mentioned (but not all of them).  Perhaps 
apropos, apropos-command, apropos-variable, apropos-function?

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 12:00:54 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> >> What do you mean by "other UI elements"?
> >
> > The mode line, the scroll bars, the menu and the tool bar.
> >
> 
> The effect on the mode line is show on the fly, see the video Yuan Fu 
> made.  For the scroll bars, the menu and the tool bar, I don't know if it 
> is possible to change their appearance within Emacs.  Is it possible?

It depends.  My point, though, is that when one needs to choose from a
large number of themes, showing how Emacs will look under a theme
makes the selection process easier.  So an image sounds like a good
way of showing the effect without requiring any action on the user.
Images also make it simpler comparing the effects of several themes.

> >> Yes, but what I meant is to have a list of font names in the buffer, 
> >> and choosing a font by clicking on the font name.
> >
> > Why?  The Options menu item I've mentioned pops up the system's font 
> > selection dialog, which is way nicer than selecting a font from an Emacs 
> > buffer.  To say nothing of being less work.  What am I missing?
> >
> 
> You're not missing anything.  It's just convenience for new users, telling 
> them to go there and there to do this and that is more confusing than 
> offering them a limited number of options during the guided tour.

You don't need to tell the user do anything, you can pop up the font
selection dialog programmatically.

> >> It's just an option.  In the video by Yuan Fu ( 
> >> https://youtu.be/0qMskTAR2aw ) you'll see that this screen is a list of 
> >> checkboxes that the user can tick.
> >
> > My point is that we should not put there unimportant options, let alone 
> > those which we recommend not to change from the defaults.
> >
> 
> I think the criterion here is not whether an option is from our point of 
> view important or unimportant, or whether we recommend or not to change 
> its default value, but whether a user coming from another editing 
> environment is likely to want it to feel "at home".

Yes.  But that wasn't my point.  My point was that you said "it's just
an option", and I said that we should think hard about which options
we show there and which we don't.  "Important" for the users we have
in mind, sure; but are you saying they expect these UI elements to be
removed?  And if they do, could it be because they don't realize how
useful they can be?

> If Doom Emacs, Spacemacs and the like disable the tool bar and the
> scroll bar, that's an indication that it's something new users might
> want.

We don't need to be bug-for-bug compatible with Spacemacs and DOOM.
Where we think they make a mistake, we should do better.

> That being said, I agree with you that perhaps at this point some of the 
> apropos commands could be mentioned (but not all of them).  Perhaps 
> apropos, apropos-command, apropos-variable, apropos-function?

apropos-documentation is also very important.

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

>> The effect on the mode line is show on the fly, see the video Yuan Fu 
>> made.  For the scroll bars, the menu and the tool bar, I don't know if 
>> it is possible to change their appearance within Emacs.  Is it 
>> possible?
>
> It depends.  My point, though, is that when one needs to choose from a 
> large number of themes, showing how Emacs will look under a theme makes 
> the selection process easier.  So an image sounds like a good way of 
> showing the effect without requiring any action on the user. Images also 
> make it simpler comparing the effects of several themes.
>

Okay, if that's feasible in a clean way that would of course be fine. 
One potential problem I see is that the font in the picture will likely 
not match the font on the system, but that's perhaps not very important. 
Note that I would not recommend to have a "large number of themes" here, 
I'd say that 20 should be an upper bound.  I would separate them in two: 
"light mode" ones and "dark mode" ones.

>>> Why?  The Options menu item I've mentioned pops up the system's font 
>>> selection dialog, which is way nicer than selecting a font from an 
>>> Emacs buffer.  To say nothing of being less work.  What am I missing?
>>
>> You're not missing anything.  It's just convenience for new users, 
>> telling them to go there and there to do this and that is more 
>> confusing than offering them a limited number of options during the 
>> guided tour.
>
> You don't need to tell the user do anything, you can pop up the font 
> selection dialog programmatically.
>

Again if that's feasible that would of course be fine.  I did not check 
this in detail, I don't use any of these features myself.

>> I think the criterion here is not whether an option is from our point 
>> of view important or unimportant, or whether we recommend or not to 
>> change its default value, but whether a user coming from another 
>> editing environment is likely to want it to feel "at home".
>
> Yes.  But that wasn't my point.  My point was that you said "it's just 
> an option", and I said that we should think hard about which options we 
> show there and which we don't.  "Important" for the users we have in 
> mind, sure; but are you saying they expect these UI elements to be 
> removed?  And if they do, could it be because they don't realize how 
> useful they can be?
>

FWIW, yes, I do think they expect to have these UI elements to be removed. 
They want a "minimal slick UI".  Not everyone would tick that option of 
course, but having it there makes sense IMO.  I don't know "how useful 
they can be", because I don't use them myself, for example I never found 
scroll bars useful in any app, and certainly not in Emacs.  The tool bar 
could be useful, but if you look at the current toolbar from the viewpoint 
of a newbie it is not.

Let's suppose I'm a newbie: first you have two buttons to read a file 
(which one should I use? let's try C-o!), then an button to launch dired 
(likely not something a newbie would want to do), then a button which says 
"Discard (kill) current buffer" (what the heck does that mean?), then 
"Save" (okay, that should be C-s, so I don't need that button), "Undo" 
(should be C-z... hey, but where is "Redo"?), "Cut" (should be C-x), 
"Copy" (should be C-c), "Paste" (should be C-v), "Search" (should be C-f). 
Oh, is that all?  What's the purpose of that toolbar?  (If you look at 
other apps they do have these things in a toolbar, but it's because the 
toolbar has much more buttons.)

>> If Doom Emacs, Spacemacs and the like disable the tool bar and the 
>> scroll bar, that's an indication that it's something new users might 
>> want.
>
> We don't need to be bug-for-bug compatible with Spacemacs and DOOM. 
> Where we think they make a mistake, we should do better.
>

The discussion here is not whether something is a mistake or not, but what 
new users coming from another editor would likely want to see to have a 
positive feeling when they open Emacs.  As long as it does not remove an 
essential feature, that's fine IMO.

>> That being said, I agree with you that perhaps at this point some of 
>> the apropos commands could be mentioned (but not all of them). 
>> Perhaps apropos, apropos-command, apropos-variable, apropos-function?
>
> apropos-documentation is also very important.
>

Okay.

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 13:56:11 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> Let's suppose I'm a newbie: first you have two buttons to read a file 
> (which one should I use? let's try C-o!), then an button to launch dired 
> (likely not something a newbie would want to do), then a button which says 
> "Discard (kill) current buffer" (what the heck does that mean?), then 
> "Save" (okay, that should be C-s, so I don't need that button), "Undo" 
> (should be C-z... hey, but where is "Redo"?), "Cut" (should be C-x), 
> "Copy" (should be C-c), "Paste" (should be C-v), "Search" (should be C-f). 
> Oh, is that all?  What's the purpose of that toolbar?  (If you look at 
> other apps they do have these things in a toolbar, but it's because the 
> toolbar has much more buttons.)

The second button from the left has an icon that is very similar to
what many other applications use for "Open a File", and the tool-tip
for it confirms that (if someone needs a confirmation).  I don't see
why users will even try anything else.

So I think your exaggeration here is misplaced.

Or maybe you are looking at a tool bar that has text instead of
descriptive icons?  In which case that's the problem to solve.

> > We don't need to be bug-for-bug compatible with Spacemacs and DOOM. 
> > Where we think they make a mistake, we should do better.
> 
> The discussion here is not whether something is a mistake or not, but what 
> new users coming from another editor would likely want to see to have a 
> positive feeling when they open Emacs.  As long as it does not remove an 
> essential feature, that's fine IMO.

If we agree to what you say in the last sentence, fine with me.  I
guess we will next need to discuss what is "essential" and what isn't.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 12:00:54PM +0000, Gregory Heytings via Emacs development discussions. wrote:

>If there was a built-in 
>vertical mode it would be better / more intuitive.

Could you try the branch feature/icomplete-vertical? I need some testers
before adding it to master.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 01:58:27PM +0300, Eli Zaretskii wrote:
>> Date: Sat, 12 Sep 2020 10:35:06 +0000
>> From: Gregory Heytings <ghe@sdf.org>
>> cc: casouri@gmail.com, emacs-devel@gnu.org
>>
>> >> SCREEN 2: "Set the color theme", with a clickable list containing the
>> >> (currently) 16 built-in themes.  A short code snippet above that list
>> >> illustrates how code is displayed with each of these themes.
>> >
>> > The snippet will only be able to show the buffer text appearance.  For
>> > other UI elements you will need an image.  Would using an image be
>> > better here?
>>
>> What do you mean by "other UI elements"?
>
>The mode line, the scroll bars, the menu and the tool bar.
>
>> >> [It would be nice to have a way to select a default font here, but I
>> >> don't know if that feasible.]
>> >
>> > I don't think I understand what you mean by that.  Selection of the
>> > default font _is_ possible, we have in the Options menu.
>>
>> Yes, but what I meant is to have a list of font names in the buffer, and
>> choosing a font by clicking on the font name.
>
>Why?  The Options menu item I've mentioned pops up the system's font
>selection dialog, which is way nicer than selecting a font from an
>Emacs buffer.  To say nothing of being less work.  What am I missing?
>
>> >> 2. disable tool-bar-mode
>> >> 3. disable scroll-bar-mode
>> >
>> > I'd object to these two.  We have just established that the former is
>> > important for newbies.  Scroll bars are presented by many applications,
>> > so why is it important to offer to turn them off here? let the users
>> > decide about these two.
>> >
>>
>> It's just an option.  In the video by Yuan Fu (
>> https://youtu.be/0qMskTAR2aw ) you'll see that this screen is a list of
>> checkboxes that the user can tick.
>
>My point is that we should not put there unimportant options, let
>alone those which we recommend not to change from the defaults.
>
We could add and extra optional SCREEN with advanced options. The user
can click next if done with the options in this page or advanced and go
for a more detailed and longer list of options.

Like a "SCREEN 2.1" to add many "unimportant" things with more
freedom. For example we can add here to enable show-trailing-whitespace,
fill-column-indicator, auto-revert-mode, visual-line-mode, ispell
dictionaries, desktop-save-mode.

All those are options not desirable in the SCREEN2, but could make sense
for users with some editing experience but not emacs experience.

WDYT?

>> >> 10. save-place-mode and desktop-save-mode
>> >
>> > desktop-save-mode slows down startup, so it might not be suitable for
>> > users who start Emacs many times a day.
>> >
>>
>> Again it's just an option, but again it's someting that users might want
>> to enable because it's a behavior that is common in text editors.
>
>There are thousands of options in Emacs that users might want to
>enable.  This initial guide should only show those which are very
>important, recommended, and usually expected.  Options that don't
>satisfy these criteria should IMO not be in the list, because the list
>must not be too long, or you will lose many newbies who don't have
>enough patience.
>
>> >> 11. (setq uniquify-buffer-name-style 'forward uniquify-min-dir-content 1024)
>> >
>> > Why? what's wrong with the defaults here?
>> >
>>
>> This has been discussed earlier in another thread, but the current
>> defaults (uniquify-buffer-name-style set to post-forward-angle-brackets)
>> is puzzling to most users, to say the least.  A complete file name is what
>> most users would expect here.
>
>A complete file name takes too much of the screen space on the mode
>line, IMO.  You'd need to make the font used by the mode-line face to
>be much smaller, and even then it will steal too much space.
>
>> >> 14. icomplete-mode (or fido-mode?)
>> >
>> > Not sure this is a good idea, these modes present complex and
>> > potentially confusing UI.
>> >
>>
>> Users expect to see completion mechanisms in a modern editor.  Enabling
>> completion in programming modes would be a too complex task for such an
>> initial greeting, but with this the user would become aware that
>> completion mechanisms exist in Emacs.
>
>Then perhaps we need to develop a new completion mechanism.  Which
>IDEs show completion like icomplete-mode?
>
Sublime and atom have a menu pretty similar to ours. A bit more
graphical oriented, but in the same "spirit".

>> I use icomplete-mode myself, and don't understand what you mean by
>> "complex and potentially confusing UI".
>
>Type "C-x C-f" and try to look at the result with the newbies' eyes.
>First question I have is "how to go on?"  <RIGHT> arrow doesn't work.
>If the font shows the bold letters distinct enough, I'd wonder what do
>the bold letters mean.  The order in which the files are shown doesn't
>necessarily make sense, nor does the fact that it mixes directories
>with files.  Etc. etc. -- the stuff I'd wonder about goes on and on.
>This is not the completion I find, e.g., in a Web browser, so prior
>experience will not help.
>
There are two options here:

1) Add more bindings to icomplete (arrows, C-n and so on)
2) Go for fido-mode which is more "friendly" like ido.

BTW Eli, I am working improving icomplete and the default
*Completions*. You can check the feature branches. If you have special
suggestions for them they are very welcome.

With my changes in *Completions* the experience is actually similar to
zsh completion...

And with icomplete I enabled the vertical layout (as helm or ivy do) and
added some coherent bindings.

What do you have in mind?

>> >> SCREEN 6: How to find help.  Short explanation about C-h C-h, C-h m,
>> >> C-h p, C-h k / C-h w / C-h a, C-h l.
>> >
>> > This misses important help commands, we should consider the list
>> > carefully with newbies in mind.  IMO, the various apropos commands are
>> > much more important for them than other help commands.
>> >
>>
>> Well, C-h C-h gives the complete list, and C-h a starts apropos.
>
>There are several apropos commands, and they are all very important
>for discoverability.
>

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 14:16:03 +0200
> From: Ergus <spacibba@aol.com>
> Cc: Gregory Heytings <ghe@sdf.org>, casouri@gmail.com, emacs-devel@gnu.org
> 
> >My point is that we should not put there unimportant options, let
> >alone those which we recommend not to change from the defaults.
> >
> We could add and extra optional SCREEN with advanced options. The user
> can click next if done with the options in this page or advanced and go
> for a more detailed and longer list of options.

Once we come up with the list of options we consider important and
useful for this target audience, we can then discuss whether the list
is long enough to warrant splitting.

> >Then perhaps we need to develop a new completion mechanism.  Which
> >IDEs show completion like icomplete-mode?
> >
> Sublime and atom have a menu pretty similar to ours. A bit more
> graphical oriented, but in the same "spirit".

"Spirit" is not what's important here, IMO.  What's important is the
visual appearance and the available actions and their effects.  What I
see out there is similar to Company, and quite different from
icomplete-mode, even when augmented by the vertical sub-mode.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 03:34:35PM +0300, Eli Zaretskii wrote:
>> Date: Sat, 12 Sep 2020 14:16:03 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: Gregory Heytings <ghe@sdf.org>, casouri@gmail.com, emacs-devel@gnu.org
>>
>> >My point is that we should not put there unimportant options, let
>> >alone those which we recommend not to change from the defaults.
>> >
>> We could add and extra optional SCREEN with advanced options. The user
>> can click next if done with the options in this page or advanced and go
>> for a more detailed and longer list of options.
>
>Once we come up with the list of options we consider important and
>useful for this target audience, we can then discuss whether the list
>is long enough to warrant splitting.
>
Agree

>> >Then perhaps we need to develop a new completion mechanism.  Which
>> >IDEs show completion like icomplete-mode?
>> >
>> Sublime and atom have a menu pretty similar to ours. A bit more
>> graphical oriented, but in the same "spirit".
>
>"Spirit" is not what's important here, IMO.  What's important is the
>visual appearance and the available actions and their effects.  What I
>see out there is similar to Company, and quite different from
>icomplete-mode, even when augmented by the vertical sub-mode.

We have xref-find-apropos and completion-at-point. But icomplete use is
totally different to company.

icomplete is more a minibuffer completion engine useful while tipping
commands, of lookign for files. There a company panel is uncomfortable.

While company-mode is a "suggestion menu" while editing. Maybe our error
have been to consider both as a single "feature".

Dimitry is the "company boss" ;) if you want it by default I don't think
anyone will have complains about as company is in general very popular.

Most external popular completions engines like LSP support company throw
company-capf or completion-at-point.

What's do you think is better to invest time improving the
completion-at-point or port Company to vanilla?

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 15:18:02 +0200
> From: Ergus <spacibba@aol.com>
> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
> 
> >"Spirit" is not what's important here, IMO.  What's important is the
> >visual appearance and the available actions and their effects.  What I
> >see out there is similar to Company, and quite different from
> >icomplete-mode, even when augmented by the vertical sub-mode.
> 
> We have xref-find-apropos and completion-at-point. But icomplete use is
> totally different to company.
> 
> icomplete is more a minibuffer completion engine useful while tipping
> commands, of lookign for files. There a company panel is uncomfortable.
> 
> While company-mode is a "suggestion menu" while editing. Maybe our error
> have been to consider both as a single "feature".

We are miscommunicating.  I said "similar to Company", meaning that
the completion drops down a vertical list of candidates that overlays
the rest of the display.  AFAIK, no existing completion package offers
something similar.  So either we implement something similar (and
offer it in that initial tour as an option), or we have to live with
the fact that users will not find in Emacs completion that they expect
to see.  In the latter case, I wonder why icomplete is deemed a step
in the right direction, for reasons I already described: it's too
complicated and confusion, IMO.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 04:43:33PM +0300, Eli Zaretskii wrote:
>> Date: Sat, 12 Sep 2020 15:18:02 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
>>
>> >"Spirit" is not what's important here, IMO.  What's important is the
>> >visual appearance and the available actions and their effects.  What I
>> >see out there is similar to Company, and quite different from
>> >icomplete-mode, even when augmented by the vertical sub-mode.
>>
>> We have xref-find-apropos and completion-at-point. But icomplete use is
>> totally different to company.
>>
>> icomplete is more a minibuffer completion engine useful while tipping
>> commands, of lookign for files. There a company panel is uncomfortable.
>>
>> While company-mode is a "suggestion menu" while editing. Maybe our error
>> have been to consider both as a single "feature".
>
>We are miscommunicating.  I said "similar to Company", meaning that
>the completion drops down a vertical list of candidates that overlays
>the rest of the display.  AFAIK, no existing completion package offers
>something similar.

Sorry to bother with this. But I don't see how what you describe defers
from Company. I mean, what is missing in company or what is different
from your desired behavior?

I agree that company needs some work, maybe check the bindings and the
default colors.

>So either we implement something similar (and
>offer it in that initial tour as an option), or we have to live with
>the fact that users will not find in Emacs completion that they expect
>to see.  In the latter case, I wonder why icomplete is deemed a step
>in the right direction, for reasons I already described: it's too
>complicated and confusion, IMO.

icomplete is the best we have embedded. If we don't add avy + counsel we
need to improve it as much as we can for the OOTB experience without
external packages. Compared to ido it integrates much better, is simpler
and uses all the new completion infrastructure.

With some minimal changes icomplete emulates ido with much simpler
code. IMO it is the best embedded minibuffer completion we have that we
can improve easily.

At the end we will always need a completion engine for the minibuffer
anyway. Sooner or later the user will need an M-x.

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 16:17:58 +0200
> From: Ergus <spacibba@aol.com>
> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
> 
> >We are miscommunicating.  I said "similar to Company", meaning that
> >the completion drops down a vertical list of candidates that overlays
> >the rest of the display.  AFAIK, no existing completion package offers
> >something similar.
> 
> Sorry to bother with this. But I don't see how what you describe defers
> from Company. I mean, what is missing in company or what is different
> from your desired behavior?

Didn't yourself say that Company is not for completion in the
minibuffer?  Whereas we are discussing minibuffer completion?

> I agree that company needs some work, maybe check the bindings and the
> default colors.

If Company can be used for minibuffer completion, then there's no
problem.

> icomplete is the best we have embedded.

Maybe our best is not good enough in this case?  In which case, if we
want to offer newcomers an experience that they expect, we need to
implement something which we don't yet have.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 05:36:14PM +0300, Eli Zaretskii wrote:
>> Date: Sat, 12 Sep 2020 16:17:58 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
>>
>> >We are miscommunicating.  I said "similar to Company", meaning that
>> >the completion drops down a vertical list of candidates that overlays
>> >the rest of the display.  AFAIK, no existing completion package offers
>> >something similar.
>>
>> Sorry to bother with this. But I don't see how what you describe defers
>> from Company. I mean, what is missing in company or what is different
>> from your desired behavior?
>
>Didn't yourself say that Company is not for completion in the
>minibuffer?  Whereas we are discussing minibuffer completion?
>
>> I agree that company needs some work, maybe check the bindings and the
>> default colors.
>
>If Company can be used for minibuffer completion, then there's no
>problem.
>
>> icomplete is the best we have embedded.
>
>Maybe our best is not good enough in this case?  In which case, if we
>want to offer newcomers an experience that they expect, we need to
>implement something which we don't yet have.
>
Ahh now I get your point. You were referring for the minibuffer only
completion.

Maybe now I am the conservative, but a menu in the middle of the screen
is not better than one at the bottom. And developing something as
polished as helm or ivy from scratch maybe don't worth the effort and we
don;t have the manpower for that. Also many of our commands are actions
on the current text (emacs is much more command-centric) overlapping a
menu maybe is not a good idea.

Sublime has such a menu, but it is for installing applications and some
other "external" actions unrelated with direct editing. The rest of the
applications just have a right click.

Any way if you think that this is a good direction there is already:

ivy-postframe:

https://github.com/tumashu/ivy-posframe

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 05:36:14PM +0300, Eli Zaretskii wrote:
>> Date: Sat, 12 Sep 2020 16:17:58 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
>>
>> >We are miscommunicating.  I said "similar to Company", meaning that
>> >the completion drops down a vertical list of candidates that overlays
>> >the rest of the display.  AFAIK, no existing completion package offers
>> >something similar.
>>
>> Sorry to bother with this. But I don't see how what you describe defers
>> from Company. I mean, what is missing in company or what is different
>> from your desired behavior?
>
>Didn't yourself say that Company is not for completion in the
>minibuffer?  Whereas we are discussing minibuffer completion?
>
>> I agree that company needs some work, maybe check the bindings and the
>> default colors.
>
>If Company can be used for minibuffer completion, then there's no
>problem.
>
>> icomplete is the best we have embedded.
>
>Maybe our best is not good enough in this case?  In which case, if we
>want to offer newcomers an experience that they expect, we need to
>implement something which we don't yet have.
>
Eli:

Looking deeper into this, either posframe and ivy are already in
elpa. We only need to add ivy-posframe to elpa. There is also a
which-key-posframe and even a company-posframe. So we have the whole set
of featured you want.

WDYT? Add all this to vanila :\?

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 12 Sep 2020 18:25:26 +0200
> From: Ergus <spacibba@aol.com>
> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
> 
> Looking deeper into this, either posframe and ivy are already in
> elpa. We only need to add ivy-posframe to elpa. There is also a
> which-key-posframe and even a company-posframe. So we have the whole set
> of featured you want.
> 
> WDYT? Add all this to vanila :\?

We were talking about what to offer to newcomers as options, remember?

Re: Interactive guide for new users

[Yuan Fu]

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



> On Sep 12, 2020, at 1:17 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Sat, 12 Sep 2020 18:25:26 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
>> 
>> Looking deeper into this, either posframe and ivy are already in
>> elpa. We only need to add ivy-posframe to elpa. There is also a
>> which-key-posframe and even a company-posframe. So we have the whole set
>> of featured you want.
>> 
>> WDYT? Add all this to vanila :\?
> 
> We were talking about what to offer to newcomers as options, remember?

It would be nice to add the option to install and enable ivy and company in the guide, can we do this in principle (i.e., promote a elpa package)? Not talking about whether we should, but whether we can.

In the similar spirit, can we give the user the option to include Melba into package-archives?

Yuan

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

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Sat, 12 Sep 2020 13:21:15 -0400
> Cc: Gregory Heytings <ghe@sdf.org>, Ergus <spacibba@aol.com>,
>  emacs-devel@gnu.org
> 
>  Looking deeper into this, either posframe and ivy are already in
>  elpa. We only need to add ivy-posframe to elpa. There is also a
>  which-key-posframe and even a company-posframe. So we have the whole set
>  of featured you want.
> 
>  WDYT? Add all this to vanila :\?
> 
>  We were talking about what to offer to newcomers as options, remember?
> 
> It would be nice to add the option to install and enable ivy and company in the guide, can we do this in
> principle (i.e., promote a elpa package)? Not talking about whether we should, but whether we can.

We should first decide whether we want to offer such features to new
users, and only later see how to make that happen.

> In the similar spirit, can we give the user the option to include Melba into package-archives?

That question was already answered, see the Emacs FAQ.  The intention
to have the non-GNU ELPA is another answer to the same question.

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

> 
> It would be nice to add the option to install and enable ivy and company 
> in the guide, can we do this in principle (i.e., promote a elpa 
> package)? Not talking about whether we should, but whether we can.
>

I think mentioning M-x list-packages in the last screen is enough, just 
after M-x customize.  Installing and enabling a particular package would 
be too much.

Re: Interactive guide for new users

[Ergus]

On Sat, Sep 12, 2020 at 06:36:05PM +0000, Gregory Heytings via Emacs development discussions. wrote:
>
>>
>>It would be nice to add the option to install and enable ivy and 
>>company in the guide, can we do this in principle (i.e., promote a 
>>elpa package)? Not talking about whether we should, but whether we 
>>can.
>>
>
>I think mentioning M-x list-packages in the last screen is enough, 
>just after M-x customize.  Installing and enabling a particular 
>package would be too much.
>
I agree. I would prefer that this only brings native features. If a
feature is so important to go here, then probably it is important enough
to be in vanilla emacs. IMO

Re: Interactive guide for new users

[Dmitry Gutov]

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

On 12.09.2020 16:43, Eli Zaretskii wrote:
>> Date: Sat, 12 Sep 2020 15:18:02 +0200
>> From: Ergus <spacibba@aol.com>
>> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
>>
>>> "Spirit" is not what's important here, IMO.  What's important is the
>>> visual appearance and the available actions and their effects.  What I
>>> see out there is similar to Company, and quite different from
>>> icomplete-mode, even when augmented by the vertical sub-mode.
>>
>> We have xref-find-apropos and completion-at-point. But icomplete use is
>> totally different to company.
>>
>> icomplete is more a minibuffer completion engine useful while tipping
>> commands, of lookign for files. There a company panel is uncomfortable.
>>
>> While company-mode is a "suggestion menu" while editing. Maybe our error
>> have been to consider both as a single "feature".
> 
> We are miscommunicating.  I said "similar to Company", meaning that
> the completion drops down a vertical list of candidates that overlays
> the rest of the display.  AFAIK, no existing completion package offers
> something similar.

With a modest amount of work, Company could work in the minibuffer, as 
long as a frontend based on child frames is used (like 
company-posframe), `company-mode-on' is modified to allow operation 
inside minibuffer, and the minibuffer setup is altered to set 
completion-at-point-functions appropriately, so that Company knows which 
completions to offer.

That said, it would still be quite different from what VS Code, Atom and 
friends employ. See the attached screenshot for the Company-based example.

> So either we implement something similar (and
> offer it in that initial tour as an option), or we have to live with
> the fact that users will not find in Emacs completion that they expect
> to see.  In the latter case, I wonder why icomplete is deemed a step
> in the right direction, for reasons I already described: it's too
> complicated and confusion, IMO.

I don't see what's so complicated you see about icomplete-mode. If you 
have problems when trying to use it, perhaps you should ask questions?

To my knowledge, if we want to come close to what those other editors 
show, our current best bet is icomplete-vertical (or something similar 
to it) PLUS a packages that moves the minibuffer to either the center or 
the top of the frame (or makes it seem live the minibuffer has been 
moved, of course).

Here's a showcase if one such package in action:

https://raw.githubusercontent.com/honmaple/emacs-maple-minibuffer/master/screenshot/example.gif

In particular, see the examples where the dropdown is displayed at the 
top and in the middle of the frame.

The package itself is here: 
https://github.com/honmaple/emacs-maple-minibuffer

There are already several packages that try to do something like this, 
but this one seemed the most stable last time I tried.

Even so, it has unfortunate limitations like not being able to adjust 
the height according to the number of available completions. And 
different features that use minibuffer are likely to expose other sharp 
corners of this (very impressive) hack. Like, some previous version of 
icomplete-vertial failed to work with it. The current seems to work 
fine, though.

So some low-level work/redesign of minibuffer code might be needed for 
this to be ready for wide public.

Relatedly, there exists a similar effort by out very own Martin 
Rudalics, but the discussion about polishing it has died down around 
here: https://lists.gnu.org/archive/html/emacs-devel/2020-06/msg00171.html

Previously: 
https://lists.gnu.org/archive/html/emacs-devel/2020-05/msg03167.html

[-- Attachment #2: Screenshot from 2020-09-13 02-23-00.png --]
[-- Type: image/png, Size: 252137 bytes --]

Re: Interactive guide for new users

[Ergus]

On Sun, Sep 13, 2020 at 03:01:42AM +0300, Dmitry Gutov wrote:
>On 12.09.2020 16:43, Eli Zaretskii wrote:
>
>To my knowledge, if we want to come close to what those other editors 
>show, our current best bet is icomplete-vertical (or something similar 
>to it)

I think that "something similar" is ivy+counsel. It works pretty fine,
lighter than helm and it is in elpa. The api engine is very polished and
the experience in general is better than with icomplete because it also
has integrated all the completion engines, sorting and formats in a
modular way.

>PLUS a packages that moves the minibuffer to either the center 
>or the top of the frame (or makes it seem live the minibuffer has been 
>moved, of course).
>
ivy-posframe also offers this with the ivy engine. I already wrote to
the author to move it to elpa and he is asking the contributors if they
have all the gnu documentation. (He already has as he is the author of
posframe and company-posframe)

The only drawback is that posframes does not work in a terminal
interface as company do... (I totally ignore that's the difference
between a posframe and a normal window)

Any way I think it is always better to have more than one option before
deciding which one we will "officially" support.

>Here's a showcase if one such package in action:
>
>https://raw.githubusercontent.com/honmaple/emacs-maple-minibuffer/master/screenshot/example.gif
>
>In particular, see the examples where the dropdown is displayed at the 
>top and in the middle of the frame.
>
>The package itself is here: 
>https://github.com/honmaple/emacs-maple-minibuffer
>
>There are already several packages that try to do something like this, 
>but this one seemed the most stable last time I tried.
>
>Even so, it has unfortunate limitations like not being able to adjust 
>the height according to the number of available completions. And 
>different features that use minibuffer are likely to expose other 
>sharp corners of this (very impressive) hack. Like, some previous 
>version of icomplete-vertial failed to work with it. The current seems 
>to work fine, though.
>
I have been trying ivy-posframe and it seems that the posframe library
solves this for them.

>So some low-level work/redesign of minibuffer code might be needed for 
>this to be ready for wide public.
>
>Relatedly, there exists a similar effort by out very own Martin 
>Rudalics, but the discussion about polishing it has died down around 
>here: 
>https://lists.gnu.org/archive/html/emacs-devel/2020-06/msg00171.html
>
>Previously: 
>https://lists.gnu.org/archive/html/emacs-devel/2020-05/msg03167.html

Re: Interactive guide for new users

[Dmitry Gutov]

On 13.09.2020 05:35, Ergus wrote:

>> To my knowledge, if we want to come close to what those other editors 
>> show, our current best bet is icomplete-vertical (or something similar 
>> to it)
> 
> I think that "something similar" is ivy+counsel.

Indeed. icomplete and Ivy are fairly close in visual appearance, with 
icomplete being closer to "stock" experience, that's why it would be my 
#1 pick, but Ivy can be a good choice.

> It works pretty fine,
> lighter than helm and it is in elpa. The api engine is very polished and
> the experience in general is better than with icomplete because it also
> has integrated all the completion engines, sorting and formats in a
> modular way.

It does the latter through its own internal API IIRC, which I'm not 100% 
sure about, but it's not a deal breaker.

>> PLUS a packages that moves the minibuffer to either the center or the 
>> top of the frame (or makes it seem live the minibuffer has been moved, 
>> of course).
>>
> ivy-posframe also offers this with the ivy engine. I already wrote to
> the author to move it to elpa and he is asking the contributors if they
> have all the gnu documentation. (He already has as he is the author of
> posframe and company-posframe)

Indeed, it's kinda weird to have both posframe and ivy in ELPA, but not 
posframe-ivy. Which will be required for the experience we are probably 
looking for.

You should try maple-minibuffer, though. It might be easier to get it 
in, with just one author.

> The only drawback is that posframes does not work in a terminal
> interface as company do... (I totally ignore that's the difference
> between a posframe and a normal window)

And the other drawbacks that packages like maple-minibuffer have, like 
having to use fixed height, which shouldn't be necessary for a popup on 
top of the frame.

Those aren't huge problems, so if we managed to get this kind of 
behavior into the default set, and maybe even get more core devs to try 
to use it, it could result in something positive.

> Any way I think it is always better to have more than one option before
> deciding which one we will "officially" support.

No objections here ;-)

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

>>> To my knowledge, if we want to come close to what those other editors 
>>> show, our current best bet is icomplete-vertical (or something similar 
>>> to it)
>> 
>> I think that "something similar" is ivy+counsel.
>
> Indeed. icomplete and Ivy are fairly close in visual appearance, with 
> icomplete being closer to "stock" experience, that's why it would be my 
> #1 pick, but Ivy can be a good choice.
>

Apart from the vertical presentation (which icomplete will apparently soon 
have), does ivy have a feature that icomplete does not have?  I can't find 
one myself, but perhaps I'm missing something.

Re: Interactive guide for new users

[Thibaut Verron]

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

Le lun. 14 sept. 2020 à 00:11, Gregory Heytings via Emacs development
discussions. <emacs-devel@gnu.org> a écrit :

> Apart from the vertical presentation (which icomplete will apparently soon
> have), does ivy have a feature that icomplete does not have?  I can't find
> one myself, but perhaps I'm missing something.
>

Does icomplete support different actions on the completion?

For example, if I want to insert a file name with completion, I can do C-x
C-f (counsel-find-file), use ivy-completion to get the name, then M-o pops
a list of actions and tells me to press i to insert the file I selected.
For such an action which I do quite rarely, I find it easier than remember
how to invoke insert-file-name (including the name of the actual function).

Counsel offers many more actions (which I don't use), including
open-literally and open with an external program, and also filesystem
actions such as copy, delete or rename.
Other actions are offered for buffers, for isearch matches, etc.

To me it feels very non-intrusive, what you don't use won't come to bite
you. But it also goes beyond the scope of a mere completion mechanism.

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

Re: Interactive guide for new users

[E]

On 9/14/20 7:20 AM, Thibaut Verron wrote:
> Le lun. 14 sept. 2020 à 00:11, Gregory Heytings via Emacs development 
> discussions. <emacs-devel@gnu.org <mailto:emacs-devel@gnu.org>> a écrit :
>
>     Apart from the vertical presentation (which icomplete will apparently soon
>     have), does ivy have a feature that icomplete does not have?  I can't find
>     one myself, but perhaps I'm missing something.
>
>
> Does icomplete support different actions on the completion?
>
> For example, if I want to insert a file name with completion, I can do C-x C-f 
> (counsel-find-file), use ivy-completion to get the name, then M-o pops a list 
> of actions and tells me to press i to insert the file I selected. For such an 
> action which I do quite rarely, I find it easier than remember how to invoke 
> insert-file-name (including the name of the actual function).

One option is Embark <https://github.com/oantolin/embark>, by the author of 
Icomplete Vertical. It can be used to add alternative actions to completion 
frameworks like Icomplete and Selectrum.

Re: Interactive guide for new users

[Ergus]

On Mon, Sep 14, 2020 at 11:42:21PM +0000, E wrote:
>On 9/14/20 7:20 AM, Thibaut Verron wrote:
>> Le�lun. 14 sept. 2020 �00:11, Gregory Heytings via Emacs development
>> discussions. <emacs-devel@gnu.org <mailto:emacs-devel@gnu.org>> a �crit�:
>>
>>     Apart from the vertical presentation (which icomplete will apparently soon
>>     have), does ivy have a feature that icomplete does not have?� I can't find
>>     one myself, but perhaps I'm missing something.
>>
>>
>> Does icomplete support different actions on the completion?
>>
>> For example, if I want to insert a file name with completion, I can do C-x C-f
>> (counsel-find-file), use ivy-completion to get the name, then M-o pops a list
>> of actions and tells me to press i to insert the file I selected. For such an
>> action which I do quite rarely, I find it easier than remember how to invoke
>> insert-file-name (including the name of the actual function).
>
>One option is Embark <https://github.com/oantolin/embark>, by the author of
>Icomplete Vertical. It can be used to add alternative actions to completion
>frameworks like Icomplete and Selectrum.
>
>
This looks nice but only this is longer than all icomplete itself.

Re: Interactive guide for new users

[E]

On 9/15/20 3:40 AM, Ergus wrote:
> 
> On Mon, Sep 14, 2020 at 11:42:21PM +0000, E wrote:
>> On 9/14/20 7:20 AM, Thibaut Verron wrote:
>>> Le�lun. 14 sept. 2020 �00:11, Gregory Heytings via Emacs development
>>> discussions. <emacs-devel@gnu.org <mailto:emacs-devel@gnu.org>> a �crit�:
>>>
>>>      Apart from the vertical presentation (which icomplete will apparently soon
>>>      have), does ivy have a feature that icomplete does not have?� I can't find
>>>      one myself, but perhaps I'm missing something.
>>>
>>>
>>> Does icomplete support different actions on the completion?
>>>
>>> For example, if I want to insert a file name with completion, I can do C-x C-f
>>> (counsel-find-file), use ivy-completion to get the name, then M-o pops a list
>>> of actions and tells me to press i to insert the file I selected. For such an
>>> action which I do quite rarely, I find it easier than remember how to invoke
>>> insert-file-name (including the name of the actual function).
>>
>> One option is Embark <https://github.com/oantolin/embark>, by the author of
>> Icomplete Vertical. It can be used to add alternative actions to completion
>> frameworks like Icomplete and Selectrum.
>>
>>
> This looks nice but only this is longer than all icomplete itself.

I feel like it's not fair to judge Embark by length, since it isn't building 
upon many existing features, and comes with several commands already defined. I 
don't think that the author would intentionally make the package more 
complicated than it has to be.

Re: Interactive guide for new users

[Stephen Leake]

Thibaut Verron <thibaut.verron@gmail.com> writes:

> Le lun. 14 sept. 2020 à 00:11, Gregory Heytings via Emacs development
> discussions. <emacs-devel@gnu.org> a écrit :
>
>> Apart from the vertical presentation (which icomplete will apparently soon
>> have), does ivy have a feature that icomplete does not have?  I can't find
>> one myself, but perhaps I'm missing something.
>>
>
> Does icomplete support different actions on the completion?
>
> For example, if I want to insert a file name with completion, I can do C-x
> C-f (counsel-find-file), use ivy-completion to get the name, then M-o pops
> a list of actions and tells me to press i to insert the file I selected.
> For such an action which I do quite rarely, I find it easier than remember
> how to invoke insert-file-name (including the name of the actual
> function).

That functionality is apparently provided by counsel, not by ivy.

Presumably counsel also works with icomplete; is that combination
missing anything?

-- 
-- Stephe

Re: Interactive guide for new users

[Thibaut Verron]

> > For example, if I want to insert a file name with completion, I can do C-x
> > C-f (counsel-find-file), use ivy-completion to get the name, then M-o pops
> > a list of actions and tells me to press i to insert the file I selected.
> > For such an action which I do quite rarely, I find it easier than remember
> > how to invoke insert-file-name (including the name of the actual
> > function).
>
> That functionality is apparently provided by counsel, not by ivy.

I do not know how much ivy and counsel are separated here. I looked
for a pure ivy entry point to find-file before answering, but all I
could find was counsel-find-file.

On the other hand, both ivy-switch-buffer and counsel-switch-buffer
offer such a choice of actions on M-o.

> Presumably counsel also works with icomplete; is that combination
> missing anything?

I do not have any experience with that.

Re: Interactive guide for new users

[E]

On 9/15/20 8:10 AM, Stephen Leake wrote:
>>
>> For example, if I want to insert a file name with completion, I can do C-x
>> C-f (counsel-find-file), use ivy-completion to get the name, then M-o pops
>> a list of actions and tells me to press i to insert the file I selected.
>> For such an action which I do quite rarely, I find it easier than remember
>> how to invoke insert-file-name (including the name of the actual
>> function).
> 
> That functionality is apparently provided by counsel, not by ivy.
> 
> Presumably counsel also works with icomplete; is that combination
> missing anything?
> 
> --
> -- Stephe
> 

Counsel is a package with many commands that use Ivy's functions specifically. I 
wouldn't assume that is would work with Icomplete.

You can see the file here:
https://github.com/abo-abo/swiper/blob/master/counsel.el

The alternative actions are created by providing arguments to `ivy-set-actions', 
and Counsel commands needing completion use `ivy-read'.

Re: Interactive guide for new users

[Dmitry Gutov]

On 13.09.2020 05:35, Ergus wrote:
>> Even so, it has unfortunate limitations like not being able to adjust 
>> the height according to the number of available completions. And 
>> different features that use minibuffer are likely to expose other 
>> sharp corners of this (very impressive) hack. Like, some previous 
>> version of icomplete-vertial failed to work with it. The current seems 
>> to work fine, though.
>>
> I have been trying ivy-posframe and it seems that the posframe library
> solves this for them.

Sorry, missed this reply.

Indeed, the height issue seems to be solved there. I don't 100% like how 
it behaves in the middle of the frame, but that can be improved too. No 
fundamental limitations there, at least.

Re: Interactive guide for new users

[Tim Van den Langenbergh]

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

On Sunday, 13 September 2020 04:35:22 CEST Ergus wrote:
> I think that "something similar" is ivy+counsel. It works pretty fine,
> lighter than helm and it is in elpa. The api engine is very polished and
> the experience in general is better than with icomplete because it also
> has integrated all the completion engines, sorting and formats in a
> modular way.

Well, ivy still has the problem that it doesn't handle file finding properly.
(I.E. in normal find-file I can type ~/.c/r/r<TAB> and it gets auto-completed
to ~/.config/retroarch/re with further completions. If I try that with Ivy I
get ~/.cache/r/r without further completions.)
Icomplete is fine, though.

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Interactive guide for new users

[Ergus]

On Sun, Sep 13, 2020 at 08:20:23PM +0200, Tim Van den Langenbergh wrote:
>On Sunday, 13 September 2020 04:35:22 CEST Ergus wrote:
>> I think that "something similar" is ivy+counsel. It works pretty fine,
>> lighter than helm and it is in elpa. The api engine is very polished and
>> the experience in general is better than with icomplete because it also
>> has integrated all the completion engines, sorting and formats in a
>> modular way.
>
>Well, ivy still has the problem that it doesn't handle file finding properly.
>(I.E. in normal find-file I can type ~/.c/r/r<TAB> and it gets auto-completed
>to ~/.config/retroarch/re with further completions. If I try that with Ivy I
>get ~/.cache/r/r without further completions.)
>Icomplete is fine, though.

I have never used that :p. Any way did you report that in the ivy
repository issues?  @abo-abo usually solves that kind of problems very
quickly.

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

>
> To my knowledge, if we want to come close to what those other editors 
> show, our current best bet is icomplete-vertical (or something similar 
> to it) PLUS a packages that moves the minibuffer to either the center or 
> the top of the frame (or makes it seem live the minibuffer has been 
> moved, of course).
>

FWIW, I don't think this is necessary.  We should not aim at creating a 
(visual) clone of some other editor.  Icomplete with a vertical candidates 
list is IMO intuitive enough for new users to adapt to it.  Emacs' 
commands are entered at the bottom of the frame, contrary to what some / 
most other editors do, and AFAICS this is fine.

Re: Interactive guide for new users

[Eli Zaretskii]

> Cc: ghe@sdf.org, casouri@gmail.com, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 13 Sep 2020 03:01:42 +0300
> 
> I don't see what's so complicated you see about icomplete-mode. If you 
> have problems when trying to use it, perhaps you should ask questions?

It isn't complicated for me, I'm familiar with icomplete-mode for
quite some time.  I think it will be complicated and confusing for
newcomers, especially if they expect a very different style of
completion.  Company is much closer to what they expect, I think.

> To my knowledge, if we want to come close to what those other editors 
> show, our current best bet is icomplete-vertical (or something similar 
> to it) PLUS a packages that moves the minibuffer to either the center or 
> the top of the frame (or makes it seem live the minibuffer has been 
> moved, of course).

Those have an annoying misfeature of causing jumps in the window above
the minibuffer.

Other possibilities exist, but my point is that if we want to offer a
better completion to make it easier for newcomers who expect something
like that, we should work on a completion style that they expect, or
something very similar, and icomplete-mode isn't.

Re: Interactive guide for new users

[John Yates]

On Sun, Sep 13, 2020 at 10:05 AM Eli Zaretskii <eliz@gnu.org> wrote:
> > From: Dmitry Gutov <dgutov@yandex.ru>
>
> > To my knowledge, if we want to come close to what those other editors
> > show, our current best bet is icomplete-vertical (or something similar
> > to it) PLUS a packages that moves the minibuffer to either the center or
> > the top of the frame (or makes it seem live the minibuffer has been
> > moved, of course).
>
> Those have an annoying misfeature of causing jumps in the window above
> the minibuffer.

Over the decades, as I have moved from a 24 line VT-100 to 32" 4K
/ 3840x2160 pixwl monitor with more than 80 lines of text, one of
the least pleasant changes in using emacs as has been the distance
my eyestravel to reach the minibuffer.

When a buffer contains fewer lines than its window the text is
vertically justified against the top of the window.  Thus my eyes
regularly flick from screen top to bottom and back.  Furthermore,
where previously, on screens with fewer lines, the minibuffer
remained within my field of view, today that is no longer the
case.

IIUC, the misfeature to which Eli refers is a desire to preserve
visibility of a window's top line in the face of window resizing.
That is surely not unexpected behavior.  My guess is this model
springs from a desire to keep as much relevant context on screen
as possible.

An alternative UI model would be to think of growing a frame top
minibuffer as dropping down a shade over the existing window(s).
This dropping down would not trigger resizing.  Instead it would
obscure as much of the visible window(s) as necessary (at least
until the shade hits a window mode line or lower border).

/john

Re: Interactive guide for new users

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Sun, 13 Sep 2020 12:38:14 -0400
> Cc: Dmitry Gutov <dgutov@yandex.ru>, ghe@sdf.org, Ergus <spacibba@aol.com>, 
> 	Yuan Fu <casouri@gmail.com>, Emacs developers <emacs-devel@gnu.org>
> 
> IIUC, the misfeature to which Eli refers is a desire to preserve
> visibility of a window's top line in the face of window resizing.

No, the reason is that Emacs always keeps point visible.  So when the
mini-window needs to be expanded in a way that will hide the point's
line, the selected window will scroll to keep point visible.

Re: Interactive guide for new users

[Dmitry Gutov]

On 13.09.2020 19:38, John Yates wrote:
> An alternative UI model would be to think of growing a frame top
> minibuffer as dropping down a shade over the existing window(s).
> This dropping down would not trigger resizing.  Instead it would
> obscure as much of the visible window(s) as necessary (at least
> until the shade hits a window mode line or lower border).

That's what maple-minibuffer does, mentioned in my previous email in 
this thread. With a link to a screencast.

Re: Interactive guide for new users

[John Yates]

On Sun, Sep 13, 2020 at 1:39 PM Dmitry Gutov <dgutov@yandex.ru> wrote:
>
> On 13.09.2020 19:38, John Yates wrote:
> > An alternative UI model would be to think of growing a frame top
> > minibuffer as dropping down a shade over the existing window(s).
> > This dropping down would not trigger resizing.  Instead it would
> > obscure as much of the visible window(s) as necessary (at least
> > until the shade hits a window mode line or lower border).
>
> That's what maple-minibuffer does, mentioned in my previous email in
> this thread. With a link to a screencast.

Only up to a point...

The pop-up frame is fixed size.  When the maple framei s not
popped up the minibuffer remains at the bottom of the frame.

My druthers on a large screen would be to have:

* The minibuffer always at the top of the frame
* Window mode lines at the top of their windows
* On growing the minibuffer, no attempt to keep point or windows visible
  (i.e. a variable-height drop-down shade)

/john

Re: Interactive guide for new users

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Mon, 14 Sep 2020 08:41:21 -0400
> Cc: Eli Zaretskii <eliz@gnu.org>, ghe@sdf.org, Ergus <spacibba@aol.com>, 
> 	Yuan Fu <casouri@gmail.com>, Emacs developers <emacs-devel@gnu.org>
> 
> * On growing the minibuffer, no attempt to keep point or windows visible

That'd be a misfeature, no?  The text you were working on or reading
will disappear from view.  To say nothing about the fact this would
mean a major surgery of the display code.

>   (i.e. a variable-height drop-down shade)

Can you elaborate about this (and its relevance to growing the
mini-window)?  I don't think I see the relation.

Re: Interactive guide for new users

[John Yates]

On Mon, Sep 14, 2020 at 11:28 AM Eli Zaretskii <eliz@gnu.org> wrote:
> > From: John Yates <john@yates-sheets.org>
> >
> > * On growing the minibuffer, no attempt to keep point or windows visible
>
> That'd be a misfeature, no?  The text you were working on or reading
> will disappear from view.  To say nothing about the fact this would
> mean a major surgery of the display code.

I do not feel so.  In most other UIs to which I have been exposed,
when a dialog box pops up, there is usually no attempt to preserve
visibility of any particular portion of the underlying application.
Sometimes the dialog box can be dragged but my impression is that
an increasing number of frameworks are foregoing that nicity.  My
guess is that this is because, with properly designed interactions,
it is exceedingly rare to need to refer back to the underlying
application in order to complete the dialog box interaction.

> >  (i.e. a variable-height drop-down shade)
>
> Can you elaborate about this (and its relevance to growing the
> mini-window)?  I don't think I see the relation.

Forgive me if I inaccurately conflate the minibuffer and the echo
area.  Let me try some pictures.


Minibuffer in its minimal, collapsed, single line state:

+=========================== Top of Frame ==========================
| Minibuffer line 1
+------------------------ Top Edge Window 1 ------------------------
| Window 1 Mode line
+-------------------------------------------------------------------
| a
| b
| c
| Window 1 contents
| x
| y
| z
+----------------------- Top Edge Window 2 ------------------------
| Window 2 Mode line
+-------------------------------------------------------------------
| p
| q
| r
| Window 1 contents
| u
| v
| w
+-======================== Bottom of Frame =========================



Minibuffer grows by one line, "shading" the first mode line:

+=========================== Top of Frame ==========================
| Minibuffer line 1
| Minibuffer line 2
+-------------------------------------------------------------------
| a
| b
| c
| Window 1 contents
| x
| y
| z
+------------------------ Top Edge Window 2 ------------------------
| Window 2 Mode line
+-------------------------------------------------------------------
| p
| q
| r
| Window 1 contents
| u
| v
| w
+========================= Bottom of Frame =========================



Minibuffer grows to five lines, "shading" 3 lines of window 1's contents:

+=========================== Top of Frame ==========================
| Minibuffer line 1
| Minibuffer line 2
| Minibuffer line 3
| Minibuffer line 4
| Minibuffer line 5
+-------------------------------------------------------------------
| Window 1 contents
| x
| y
| z
+------------------------ Top Edge Window 2 ------------------------
| Window 2 Mode line
+-------------------------------------------------------------------
| p
| q
| r
| Window 1 contents
| u
| v
| w
+========================= Bottom of Frame =========================


It is this minibuffer growing from the top of the frame downward and
obscuring whatever it encounters that I describe as a "drop down shade".

I understand that this is a new display behavior.  That said, is it
not simpler and entirely independent of how resizing the minibuffer
works today?

/john

Re: Interactive guide for new users

[Göktuğ Kayaalp]

On 2020-09-15 04:42 +03, John Yates <john@yates-sheets.org> wrote:
>> That'd be a misfeature, no?  The text you were working on or reading
>> will disappear from view.  To say nothing about the fact this would
>> mean a major surgery of the display code.
> I do not feel so.  In most other UIs to which I have been exposed,
> when a dialog box pops up, there is usually no attempt to preserve
> visibility of any particular portion of the underlying application.
> Sometimes the dialog box can be dragged but my impression is that
> an increasing number of frameworks are foregoing that nicity.  My
> guess is that this is because, with properly designed interactions,
> it is exceedingly rare to need to refer back to the underlying
> application in order to complete the dialog box interaction.

Emacs supports far richer interactions than usual desktop applications
(some examples in the questions below).  It’s more than just ‘referring
back’ in Emacs’ case.

> Minibuffer in its minimal, collapsed, single line state:
[... snip ...]
> Minibuffer grows by one line, "shading" the first mode line:
[... snip ...]
> Minibuffer grows to five lines, "shading" 3 lines of window 1's contents:
[... snip ...]
> It is this minibuffer growing from the top of the frame downward and
> obscuring whatever it encounters that I describe as a "drop down shade".
>
> I understand that this is a new display behavior.  That said, is it
> not simpler and entirely independent of how resizing the minibuffer
> works today?

1) How does this interact with a scenario where user goes back and forth
   between editing the minibuffer vs. some displayed buffer?

2) One might be looking at their notes while editing the minibuffer.
   E.g. imagine reading some docs and M-xing some commands from it, or
   naming an Org link, etc.

3) Would it be possible to revert this back to the current behaviour
   with a user option?

4) How is this better than how other editors do their ‘command
   palettes’? Isn’t it better to just pop up a centered frame and do
   completions there?  With the added benefit of being able to move the
   thing around and focus back to the buffer.

5) While a command palette at the bottom of the application is somewhat
   obscure, one up top is probably novel.  Frankly I don’t like the idea
   of having a single empty line right in the line of my sight,
   constantly, taking up space right where my eyes go by default when
   reading stuff.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Interactive guide for new users

[John Yates]

On Tue, Sep 15, 2020 at 3:01 AM Göktuğ Kayaalp <self@gkayaalp.com> wrote:

> 1) How does this interact with a scenario where user goes back and forth
> between editing the minibuffer vs. some displayed buffer?

I am aware that the current behavior supports this possible style
of interaction.  I cannot remember having ever used it myself.
Based on that experience my attitude is that such interactions
are rare enough that I am willing to disadvantage them a bit to
improve the more common cases.

To restore the ability to interact as you have described I
suggest a key binding to re-layout the all windows, including
the expanded minibuffer.

Would that not allow you to carry out your back and forth
interactions just as you would do today?

> 2) One might be looking at their notes while editing the minibuffer.
> E.g. imagine reading some docs and M-xing some commands from it, or
> naming an Org link, etc.

I am not sure I follow.

While one is reading the doc and M-xing commands, the minibuffer
is likely to be in its minimal, collapsed state, just as it would
be today.  Even if, while executing some M-x command, the
minibuffer were to grow to overlap some portion of the visible
window(s) I contend that, most likely, the user would complete
that interaction, thereby causing the minibuffer to revert to its
collapsed state, prior to the user needing to return to his/her
source document.

> 3) Would it be possible to revert this back to the current behaviour
> with a user option?

Of course.  That is the emacs way.  And, were such minibuffer
behavior ever to become available, I cannot imagine it being
shipped as the default.  It would be opt-in.

> 4) How is this better than how other editors do their ‘command
> palettes’? Isn’t it better to just pop up a centered frame and do
> completions there?   With the added benefit of being able to move the
> thing around and focus back to the buffer.

If you go back to when I first joined the thread you will see
that I am especially interested in optimizing emacs on very
large, hi res screens.  Popping up a dialog box in the middle of
such a screen is nearly as bad as expanding the minibuffer up
from the bottom of the screen.

I find the prospect of needing to drag a dialog box around less
appealing than the single key binding to re-layout the windows
(as suggested above).  A key binding is definitely more consitent
with emacs' traditional solutions.

> 5) While a command palette at the bottom of the application is somewhat
> obscure, one up top is probably novel. Frankly I don’t like the idea
> of having a single empty line right in the line of my sight,
> constantly, taking up space right where my eyes go by default when
> reading stuff.

You must live in a world devoid of title bars nor menu bars.

/john

Re: Interactive guide for new users

[Göktuğ Kayaalp]

On 2020-09-16 06:30 +03, John Yates <john@yates-sheets.org> wrote:
> On Tue, Sep 15, 2020 at 3:01 AM Göktuğ Kayaalp <self@gkayaalp.com> wrote:
>> 3) Would it be possible to revert this back to the current behaviour
>> with a user option?
> Of course.  That is the emacs way.  And, were such minibuffer
> behavior ever to become available, I cannot imagine it being
> shipped as the default.  It would be opt-in.

Well that makes any other talk unnecessary.  So long as it’s an addition
and not a replacement (sorry for not noticing that part, a lot of
suggestions in these threads are at the cost of breaking existing users’
workflows that I read yours with some prejudice), it’s all the better
for everyone.  Good old TIMTOWDY.

>> 5) While a command palette at the bottom of the application is somewhat
>> obscure, one up top is probably novel. Frankly I don’t like the idea
>> of having a single empty line right in the line of my sight,
>> constantly, taking up space right where my eyes go by default when
>> reading stuff.
> You must live in a world devoid of title bars nor menu bars.

FWIW, that’s been the case for a pretty long time, and even these days
where I’m on a more traditional desktop (Cinnamon) I rarely find myself
using menus.  Tho the set of applications I consistently use is rather
small (Emacs, Qutebrowser/Firefox, Okular, Zotero, Terminal every now
and then), so I tend to know a decent chunk of keyboard shortcuts.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Interactive guide for new users

[Eli Zaretskii]

> From: John Yates <john@yates-sheets.org>
> Date: Mon, 14 Sep 2020 21:42:42 -0400
> Cc: Dmitry Gutov <dgutov@yandex.ru>, ghe@sdf.org, Ergus <spacibba@aol.com>, 
> 	Yuan Fu <casouri@gmail.com>, Emacs developers <emacs-devel@gnu.org>
> 
> > >  (i.e. a variable-height drop-down shade)
> >
> > Can you elaborate about this (and its relevance to growing the
> > mini-window)?  I don't think I see the relation.
> 
> Forgive me if I inaccurately conflate the minibuffer and the echo
> area.  Let me try some pictures.
> 
> 
> Minibuffer in its minimal, collapsed, single line state:

Ah, so this should go together with "minibuffer on top".  Thanks, now
everything is clear.

Re: Interactive guide for new users

[Dmitry Gutov]

On 14.09.2020 15:41, John Yates wrote:
> On Sun, Sep 13, 2020 at 1:39 PM Dmitry Gutov <dgutov@yandex.ru> wrote:
>>
>> On 13.09.2020 19:38, John Yates wrote:
>>> An alternative UI model would be to think of growing a frame top
>>> minibuffer as dropping down a shade over the existing window(s).
>>> This dropping down would not trigger resizing.  Instead it would
>>> obscure as much of the visible window(s) as necessary (at least
>>> until the shade hits a window mode line or lower border).
>>
>> That's what maple-minibuffer does, mentioned in my previous email in
>> this thread. With a link to a screencast.
> 
> Only up to a point...
> 
> The pop-up frame is fixed size.  When the maple framei s not
> popped up the minibuffer remains at the bottom of the frame.

Do you mean the echo area or the commands which use the minibuffer which 
maple-minibuffer ignores? I'm not sure why 'eval-expression' is in 
'maple-minibuffer:ignore-action' by default, but there must be some reason.

In any case, if we want this feature well-integrated, there must be some 
initiative from the maintainers toward that end.

Re: Interactive guide for new users

[Dmitry Gutov]

On 13.09.2020 17:04, Eli Zaretskii wrote:

>> I don't see what's so complicated you see about icomplete-mode. If you
>> have problems when trying to use it, perhaps you should ask questions?
> 
> It isn't complicated for me, I'm familiar with icomplete-mode for
> quite some time.  I think it will be complicated and confusing for
> newcomers, especially if they expect a very different style of
> completion.

Perhaps. But it's a bridge between what the oldies

> Company is much closer to what they expect, I think.

But you didn't even care to acknowledge the company-based example in my 
previous email?

>> To my knowledge, if we want to come close to what those other editors
>> show, our current best bet is icomplete-vertical (or something similar
>> to it) PLUS a packages that moves the minibuffer to either the center or
>> the top of the frame (or makes it seem live the minibuffer has been
>> moved, of course).
> 
> Those have an annoying misfeature of causing jumps in the window above
> the minibuffer.

No, they don't. That's the point.

Did you look at the screencast gif?

> Other possibilities exist, but my point is that if we want to offer a
> better completion to make it easier for newcomers who expect something
> like that, we should work on a completion style that they expect, or
> something very similar, and icomplete-mode isn't.

Have you tried icomplete-vertical?

Whether we choose icomplete or Ivy, though, the issue of being able to 
offer a UI where the minibuffer is overlayed on top of the frame is 
something we should work on. And it's something tied to a lower level 
functionality than just completion styles (the minibuffer, the echo 
area, and the frames display logic).

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

>> To my knowledge, if we want to come close to what those other editors 
>> show, our current best bet is icomplete-vertical (or something similar 
>> to it) PLUS a packages that moves the minibuffer to either the center 
>> or the top of the frame (or makes it seem live the minibuffer has been 
>> moved, of course).
>
> Those have an annoying misfeature of causing jumps in the window above 
> the minibuffer.
>
> Other possibilities exist, but my point is that if we want to offer a 
> better completion to make it easier for newcomers who expect something 
> like that, we should work on a completion style that they expect, or 
> something very similar, and icomplete-mode isn't.
>

I never noticed that misfeature before you mentioned it, and I agree with 
you that it could surprise newcomers.  However, with (setq 
scroll-conservatively 101), which is one of the suggested options in the 
proposal, its effect is much more limited, and I believe newcomers would 
not be surprised anymore.

Re: Interactive guide for new users

[Elias Mårtenson]

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

On Sat, 12 Sep 2020, 18:36 Gregory Heytings via Emacs development
discussions., <emacs-devel@gnu.org> wrote:

>
> "Not now" would not do anything, so the initial greeting would be executed
> again the next time Emacs is started.  And "Don't show this again" would
> create an empty ~/.emacs / ~/.emacs.d/init.el, so the initial greeting
> would not be executed again.
>

At the risk of adding to the bikeshedding, may I ask that if you click on
"don't display again", the UI displays a brief explanation that it created
the file and where it is?

It's a pet peeve of mine because in many applications I have selected such
options accidentally and then had no way to find out how to get back to the
original state.

>

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

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Elias Mårtenson <lokedhs@gmail.com>
> Date: Sat, 26 Sep 2020 17:16:47 +0800
> Cc: Eli Zaretskii <eliz@gnu.org>, Yuan Fu <casouri@gmail.com>, emacs-devel@gnu.org
> 
>  "Not now" would not do anything, so the initial greeting would be executed 
>  again the next time Emacs is started.  And "Don't show this again" would 
>  create an empty ~/.emacs / ~/.emacs.d/init.el, so the initial greeting 
>  would not be executed again.
> 
> At the risk of adding to the bikeshedding, may I ask that if you click on "don't display again", the UI displays a
> brief explanation that it created the file and where it is? 
> 
> It's a pet peeve of mine because in many applications I have selected such options accidentally and then had
> no way to find out how to get back to the original state. 

Perhaps a better way would be to have a menu item that "displays
again" the initial greeting?  (That could be in addition to the brief
explanation you propose displaying.)

RE: Interactive guide for new users

[Drew Adams]

> may I ask that if you click on "don't display again",
> the UI displays a brief explanation that it created
> the file and where it is? 
>
> It's a pet peeve of mine because in many applications
> I have selected such options accidentally and then
> had no way to find out how to get back to the original state.

Yup.  It's a pain to have to google later to
find out how to set/unset/reset some setting
(preference).

Particularly a setting you chose (especially
if forced to choose) on the fly when you
brought up an app for the first time.

Re: Interactive guide for new users

[Eli Zaretskii]

> Date: Sat, 26 Sep 2020 07:38:21 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Yuan Fu <casouri@gmail.com>,
>         emacs-devel@gnu.org
> 
> > may I ask that if you click on "don't display again",
> > the UI displays a brief explanation that it created
> > the file and where it is? 
> >
> > It's a pet peeve of mine because in many applications
> > I have selected such options accidentally and then
> > had no way to find out how to get back to the original state.
> 
> Yup.  It's a pain to have to google later to
> find out how to set/unset/reset some setting
> (preference).

They will google anyway.

RE: Interactive guide for new users

[Drew Adams]

> > > may I ask that if you click on "don't display again",
> > > the UI displays a brief explanation that it created
> > > the file and where it is?
> > >
> > > It's a pet peeve of mine because in many applications
> > > I have selected such options accidentally and then
> > > had no way to find out how to get back to the original state.
> >
> > Yup.  It's a pain to have to google later to
> > find out how to set/unset/reset some setting
> > (preference).
> 
> They will google anyway.

Maybe some.  Not all.  If we tell them, then they
won't _have_ to google.  But yes, some will google
anyway.

Re: Interactive guide for new users

[Andreas Schwab]

On Sep 26 2020, Drew Adams wrote:

>> may I ask that if you click on "don't display again",
>> the UI displays a brief explanation that it created
>> the file and where it is? 
>>
>> It's a pet peeve of mine because in many applications
>> I have selected such options accidentally and then
>> had no way to find out how to get back to the original state.
>
> Yup.  It's a pain to have to google later to
> find out how to set/unset/reset some setting
> (preference).
>
> Particularly a setting you chose (especially
> if forced to choose) on the fly when you
> brought up an app for the first time.

I don't think a transient display of the explanation will fundamentally
change the situation.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

RE: Interactive guide for new users

[Drew Adams]

> >> may I ask that if you click on "don't display again",
> >> the UI displays a brief explanation that it created
> >> the file and where it is?
> >>
> >> It's a pet peeve of mine because in many applications
> >> I have selected such options accidentally and then
> >> had no way to find out how to get back to the original state.
> >
> > Yup.  It's a pain to have to google later to
> > find out how to set/unset/reset some setting
> > (preference).
> >
> > Particularly a setting you chose (especially
> > if forced to choose) on the fly when you
> > brought up an app for the first time.
> 
> I don't think a transient display of the explanation
> will fundamentally change the situation.

I agree.  I was speaking about the problem (pet peeve),
not any particular proposed solution.

In general, Emacs is good at letting you find things
out about it, including how to undo damage or restore
things.

Re: Interactive guide for new users

[Jean Louis]

* Elias Mårtenson <lokedhs@gmail.com> [2020-09-26 12:17]:
> On Sat, 12 Sep 2020, 18:36 Gregory Heytings via Emacs development
> discussions., <emacs-devel@gnu.org> wrote:
> 
> >
> > "Not now" would not do anything, so the initial greeting would be executed
> > again the next time Emacs is started.  And "Don't show this again" would
> > create an empty ~/.emacs / ~/.emacs.d/init.el, so the initial greeting
> > would not be executed again.
> >
> 
> At the risk of adding to the bikeshedding, may I ask that if you click on
> "don't display again", the UI displays a brief explanation that it created
> the file and where it is?
> 
> It's a pet peeve of mine because in many applications I have selected such
> options accidentally and then had no way to find out how to get back to the
> original state.

That could maybe be solved by turning the imaginary
help-me-return-to-original-state-mode that could log various messages
and show hints to the user in the minibar, just as the Midnight
Commander file manager is showing it to users.

If such mode would be turned on, it would more clearly then the
message log, inform the user which file was saved and where, and how
to get to the file back.

if there is some option customized, the imaginary mode could tell to
user how to come back to it, or how to revert it, it could include the
reference to key bindings as well.

Thus it could follow the users in their actions and help them revert
back or reference those actions to other actions, making the AI within
Emacs, which is anyway what I would expect it of a computer and
software, to help me as artificial intelligence to use a computer, not
that I need to search for help on Internet.

So let us start creating the general beginner-AI-mode that is to help user and
guide the user through whatever necessary that user feel better
guided. Those C-h functions could be then connected in the flow or
workflows.

If {C-h k} is pressed, such AI mode could advice the user about other
referenced keys that are related to the one that user asked for, it
could show references. For now {C-h k} is showing what the key does
and it points it to the Lisp file. But if the kez is speaking about
the end of buffer, that could all be said in a nicer way, for
beginners, without Lisp file, and various complications, and it could
point out hyperlinks to begin of file key and various other keys
relevant to end of buffer key.

If user turns on option to remove the menu, from the Option menu, then
the Beginner's AI mode would clearly inform the user that F10 may be
pressed to come back to Menu again or {M-x toggle-menu-bar-mode-from-frame}
would bring it back. Not that the user get stuck if the menu bar is
toggled off.

espeak or other speech engine could be, should be implemented in the
Beginner's AI Mode, and such would interact with the user in similar
fashion as phone interactive menus interact with callers. User could
ask the Beginner's AI or Hal, call it as you wish, by telling "Hello
Hal" or pressing a key.

Then Hal would respond: How may I help you master? (delete "master"
for political correctness)

Then user would say "menu" or something like that, and Hal could ask
if menu bar should be toggled on, or it would open the menu. Or it
could find relevant subjects related to "deleting a line". Or it could
ask the user menu of options to choose from, user could speak to the
Hal and get things done in easy manner.

Jean

Re: Interactive guide for new users

[Göktuğ Kayaalp]

On 2020-09-12 12:55 +03, Eli Zaretskii <eliz@gnu.org> wrote:
> What is the definition of "the first time"? where will we keep the
> indication that this is/isn't "the first time"?  Also, will this
> affect "emacs -Q" or "emacs -q"?

Potential solution could be to only show this if Emacs is run without
any command line arguments, and only if the empty file
‘~/.config/emacs-28-interactive-guide-ran’ (or something similar, of
course) exists and no .emacs or init.el exists.  It not being in an
ephemeral location means the user may make sure to keep the file there
so that even if they don’t have a .emacs, they may avoid this thing
popping up every time they run Emacs.  It may be useful to also provide
an environment variable which wen set to t inhibits this without needing
a file, e.g. EMACS_INHIBIT_INTERACTIVE_TUTORIAL.

>> SCREEN 2: "Set the color theme", with a clickable list containing the
>> (currently) 16 built-in themes.  A short code snippet above that list
>> illustrates how code is displayed with each of these themes.
> The snippet will only be able to show the buffer text appearance.  For
> other UI elements you will need an image.  Would using an image be
> better here?

This probably wouldn’t work on terminal Emacs.  For a more univarsally
apllicable, you could have a single snippet, and picking a theme just
sets it globally.  A confirm button at bottom saves the preference using
customize and advances.

>> SCREEN 8: Thank you. Your choices have been saved in Emacs' configuration
>> file ~/.emacs.d/init.el (or ~/.emacs ?).
> What do we do here wrt XDG preferences?

Might be a good idea to default to XDG dirs if that’s what Emacs
community wants to encourage.  But because a lot of text out there will
say ~/.emacs or ~/.emacs.d/init.el, the file name should be made very
clear.

>> You can use M-x initial-greeting at any time to go through this
>> configuration again.
> That command should be on the Help menu.  And I think the name should
> be 'introduction-to-emacs' or somesuch.

AFAIU it’s customary in the industry these days to call these
walkthrough wizards "Guided Tours".  That might be a more recognisable
name.  ‘initial-greeting’ and ‘introduction-to-emacs’ sound rather
non-interactive to me, i.e. I’d expect to be reading stuff, deducing
from the names.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Interactive guide for new users

[Gregory Heytings via Emacs development discussions.]

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


>>> SCREEN 2: "Set the color theme", with a clickable list containing the 
>>> (currently) 16 built-in themes.  A short code snippet above that list 
>>> illustrates how code is displayed with each of these themes.
>>
>> The snippet will only be able to show the buffer text appearance.  For 
>> other UI elements you will need an image.  Would using an image be 
>> better here?
>
> This probably wouldn’t work on terminal Emacs.  For a more univarsally 
> apllicable, you could have a single snippet, and picking a theme just 
> sets it globally.  A confirm button at bottom saves the preference using 
> customize and advances.
>

Indeed I admit I did not think about terminal Emacs.  The guided tour 
should probably also be skipped if Emacs is executed in a terminal.

>>> You can use M-x initial-greeting at any time to go through this 
>>> configuration again.
>>
>> That command should be on the Help menu.  And I think the name should 
>> be 'introduction-to-emacs' or somesuch.
>
> AFAIU it’s customary in the industry these days to call these 
> walkthrough wizards "Guided Tours".  That might be a more recognisable 
> name.  ‘initial-greeting’ and ‘introduction-to-emacs’ sound rather 
> non-interactive to me, i.e. I’d expect to be reading stuff, deducing 
> from the names.
>

I think I would also prefer guided-tour, but OTOH that name is not very 
important if it is executed automatically when Emacs starts.

Re: Interactive guide for new users

[Robert Pluim]

>>>>> On Sat, 12 Sep 2020 14:02:29 +0300, Göktuğ Kayaalp <self@gkayaalp.com> said:

    >>> SCREEN 8: Thank you. Your choices have been saved in Emacs' configuration
    >>> file ~/.emacs.d/init.el (or ~/.emacs ?).
    >> What do we do here wrt XDG preferences?

    Göktuğ> Might be a good idea to default to XDG dirs if that’s what Emacs
    Göktuğ> community wants to encourage.  But because a lot of text out there will
    Göktuğ> say ~/.emacs or ~/.emacs.d/init.el, the file name should be made very
    Göktuğ> clear.

We could default 'user-init-file' to "$XDG_CONFIG_HOME/emacs/init.el"
for people who have no existing .emacs or .emacs.d, I guess (currently
we default to ~/.emacs), although Iʼd be happier if we used
"~/.emacs.d/init.el", as that leaves the choice of whether to use XDG
later up to the user (and Emacs will create ~/.emacs.d anyway).

Iʼm in no way suggesting that we stop reading ~/.emacs, though.

Robert

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eduardo Mercovich]

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

Hi Stefan.

Sorry the delay. These are really crazy days...
  
Here is :
- a 1st general flow proposal with a point to discuss, 
- with 1 example of how each step could be structured.

The idea is to make the wizard as a framework in such a way that it's
really easy to add, remove or change each step and specific options and
defaults. We can envision a script that embodies the interaction and
takes the information (sequence, prompts, options, etc.) from an
external file, for example. 

You'll see here no internal details of each big step since they don't
make sense without context (what goes before and what follows). 

I'm including both the Dia source and a pdf just in case it appears
mangled.

I tried -still without success- to express this in text only. I would
gratefully accept suggestions of formats or structures that could work
for most of the emacs community. 

If you believe it's presentable, I can send this to the rest in the mail
thread. Of course, we can also schedule a brief talk if you'd like. Some
things are easier interactively. ;) 

I'm new to the emacs community in this depth and I know that UX is not
known much here (or in many places, still), so, I would appreciate a lot
some guidance so as not to make anyone mad with this and align
expectations, communications and styles. :) 

Best...


[-- Attachment #2: EmacsConfigurationWizard.dia --]
[-- Type: application/octet-stream, Size: 9103 bytes --]

[-- Attachment #3: EmacsConfigurationWizard.pdf --]
[-- Type: application/pdf, Size: 35932 bytes --]

[-- Attachment #4: Type: text/plain, Size: 137 bytes --]



-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

RE: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Drew Adams]

> Here is :
> - a 1st general flow proposal with a point to discuss,
> - with 1 example of how each step could be structured.

It's been said before: Please do NOT refer to such
a prepared set of settings and packages as an Emacs
"distribution".

These are not distributions.  Call them nearly
anything but that, please.

They're giant sacks of possible features and choices
of settings.  I don't care whether you call them
styles, brands, super-packages, modes, themes, or
foobars.  But they're not Emacs distributions.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eduardo Mercovich]

Hello Drew.

 [...]
 
> It's been said before: Please do NOT refer to such a prepared set of
> settings and packages as an Emacs "distribution". 

Sure!

Sorry I hurt your sensibilities/ideas with that particular word.
I never heard those talks before, nor even knew about the issue of how
they are named.

> These are not distributions. Call them nearly anything but that,
> please. [...]

I have no problem calling them whatever you'd like, since the issue is
obviously very important to you. Please, share with me your preferred
term and I'll use it from now on. :)

Best...


PD: please keep in mind that I'm not a native English speaker, in case
something seems odd in my writing. 
-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

RE: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Drew Adams]

> > It's been said before: Please do NOT refer
> > to such a prepared set of settings and
> > packages as an Emacs "distribution".
> 
> Sure!
> 
> > These are not distributions. Call them nearly
> > anything but that, please.
> 
> Please, share with me your preferred term and I'll use it from now on. :)

Sorry if my request sounded too enthusiastic.
And no, it's not particularly important to me.
I just thought the list had generally agree to
move beyond that term for such bundles.

Recently this question came up on this list, in
passing.  It's not super important, but the term
can lead to some confusion.

Here's one recent post that mentions it:

https://lists.gnu.org/archive/html/emacs-devel/2020-09/msg00666.html

I don't have a preferred term for whatever such
bundles of Emacs configurations might be called.
But avoiding "distribution" makes sense to me.

AFAIK, these are all GNU Emacs under the covers
(and above), with different default behaviors,
look & feel, etc.

In this list, so far, they've sometimes been
referred to as "starter kits" (but are all of
them only for those starting out?), and as
"canned configurations".

In some ways some of them might resemble super
"packages", super "themes", or even super global
minor "modes".

But in general I imagine they're more hard-coded,
in the sense that you either use one or you don't -
you don't combine them or switch from one to another
during an Emacs session, or turn one on/off during
a session.  In the message you responded to I used
the description "a prepared set of settings and
packages".

But not being a user of any of them, I'm not well
placed to come up with a good word to describe them.
Perhaps someone else here has a good idea about that.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Eduardo Mercovich]

Hi Drew.

[...]
>> Please, share with me your preferred term and I'll use it from now on. :)

> Sorry if my request sounded too enthusiastic. [...]

It's ok, no human has been damaged during this mail exchange. ;P

> Recently this question came up on this list, in passing. [...]

I wasn't in the list at that time, but I'll read the thread to dive a
bit into the matter, thanks. 

If it's important, we may talk with the Spacemacs, Doom, Prelude, etc.
people and agree on a term.

Thanks anyway for the heads-up on this matter, I'm all into learning
more about the Emacsverse. :)

Now, let's focus again on the configuration wizard.

Best...

-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

RE: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[Drew Adams]

> > Recently this question came up on this list, in passing.
> 
> I wasn't in the list at that time, but I'll read the thread to dive a
> bit into the matter, thanks.

It came up a few times, in different threads.
But I don't suggest you bother looking for it -
the threads are long and winding, and this was
just mentioned in passing a few times.

It's not very important.  Most here might feel
it's not important at all.

> If it's important, we may talk with the Spacemacs, Doom, Prelude, etc.
> people and agree on a term.
> 
> Thanks anyway for the heads-up on this matter, I'm all into learning
> more about the Emacsverse. :)
> 
> Now, let's focus again on the configuration wizard.

Re: Interactive guide for new users (was: Re: Gather a list of confusions beginner tend to have)

[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 it is ok to call these things "Emacs distributions" -- just
don't abbreviate that to "distributions".

I think "modified Emacs releases" would be a better term to 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: Interactive guide for new users

[Philip K.]

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. ]]]
>
> I think it is ok to call these things "Emacs distributions" -- just
> don't abbreviate that to "distributions".
>
> I think "modified Emacs releases" would be a better term to use.

They aren't real "releases" though, usually installing them just
requires downloading a preconfigured .emacs.d directory.

-- 
	Philip K.

Re: Interactive guide for new users

[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 "modified Emacs releases" would be a better term to use.

  > They aren't real "releases" though, usually installing them just
  > requires downloading a preconfigured .emacs.d directory.

In that case, the word "distribution" does not fit them either.
How about "Emacs configurations"?

-- 
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: Interactive guide for new users

[Philip K.]

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. ]]]
>
>   > > I think "modified Emacs releases" would be a better term to use.
>
>   > They aren't real "releases" though, usually installing them just
>   > requires downloading a preconfigured .emacs.d directory.
>
> In that case, the word "distribution" does not fit them either.
> How about "Emacs configurations"?

Everyone with a .emacs file has a configuration, but that's not what
Doom, Spacemacs, etc. provide. In a sense, they forked Emacs, without
forking the core code, instead providing a patch-set in Elisp form + a
DSL.

I agree, that distributions is the wrong term -- it's not the same as
with BSD or GNU/Linux, where a distribution bundles various software
into a self-sufficient form. That doesn't make sense here, as opposed to
the Linux kernel, Emacs can exist on it's own.

-- 
	Philip K.

Re: Interactive guide for new users

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

  > Everyone with a .emacs file has a configuration, but that's not what
  > Doom, Spacemacs, etc. provide. In a sense, they forked Emacs, without
  > forking the core code, instead providing a patch-set in Elisp form + a
  > DSL.

I keep receiving different descriptions of what those things consist
of.  I don't know which description is correct, but I can suggest a
term for each one.

For this description, I suggest "Emacs patch distributions."

What is a "DSL"?  And what code is in 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: Interactive guide for new users

[Okam]

On 9/23/20 9:32 PM, Richard Stallman wrote:
> 
> [[[ 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. ]]]
> 
>    > Everyone with a .emacs file has a configuration, but that's not what
>    > Doom, Spacemacs, etc. provide. In a sense, they forked Emacs, without
>    > forking the core code, instead providing a patch-set in Elisp form + a
>    > DSL.
> 
> I keep receiving different descriptions of what those things consist
> of.  I don't know which description is correct, but I can suggest a
> term for each one.


I haven't used Spacemacs in a while, but I want try to add some information, if 
it hasn't been said already.

In the case of Spacemacs, it consists of groups of packages, which they call 
"layers", based around certain general features like spell-checking or a 
particular programming language. For a programming language, a layer might 
include packages for things like syntax highlighting, error checking, and 
expanding snippets of text specifically for that language.

When a user enables/disables a layer, they are enabling/disabling the collected 
packages that the Spacemacs developers think provide a good user experience. To 
facilitate working with so many packages, the Spacemacs developers have put a 
lot thought into the loading, interaction between, and configuration of said 
packages.

Here are a few examples:
- They have tried to create standard keybinding layouts, so that, for example, 
"SPC m s" is generally the keybinding used to launch any programming language 
REPL that has a corresponding layer. This sort of consistency is helpful to new 
users.
- They set up some form of package rollback for when a package update breaks the 
configuration.
- They have tried to create a repository containing of all the packages needed 
for any layer, that they have decided is a safe version. This should hopefully 
reduced problems caused by packages changing function names, etc.
- They ask users to keep their personal configs in a "~/.spacemacs" file, to 
better work with the deferred loading of packages that they have set up.

All of these things can be done by a user of regular Emacs, because Spacemacs is 
indeed another Emacs config, but it would be a hassle for a normal user 
(especially a new user) to do it at the scale/breadth the Spacemacs developers 
are attempting.

They are not running their own version of Emacs, so calling it an "Emacs 
distribution" is odd, but thinking of it as just a config file that people copy 
from doesn't really capture the effort of their work, I think, particularly with 
projects like Spacemacs and Doom creating their own sort of configuration system.

Re: Interactive guide for new users

[Stefan Monnier]

> I think it is ok to call these things "Emacs distributions" -- just
> don't abbreviate that to "distributions".
>
> I think "modified Emacs releases" would be a better term to use.

AFAIK they do not actually distribute Emacs, only some (set of)
configuration files.

I think of them as *configs* (and I'd like them to be *implemented* as
custom themes).


        Stefan

Re: Interactive guide for new users

[Po Lu]

Richard Stallman <rms@gnu.org> writes:

> I think "modified Emacs releases" would be a better term to use.

"modified Emacs releases" is somewhat misleading, as it implies that
the Emacs used in those "modified Emacs releases" has been modified,
while most of these do not actually modify Emacs C code, or code
distributed with Emacs.

A common term used nowadays is 'starter pack'.  Perhaps that would
suffice?

Re: Interactive guide for new users

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

  > A common term used nowadays is 'starter pack'.  Perhaps that would
  > suffice?

At least it's not actively misleading or confusing.

-- 
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: Interactive guide for new users

[Philip K.]

An issue I can imagine is that a lot of the options that would be
displayed in a wizard like this wouldn't mean too much to
newcomers. "Helm" or "Ivy"? "Projectile"? Even Emacs-native packages are
often confusing ("Hippie-Expand", "Xref", etc.). Without a way to test
and find out what these options _mean_, you would only be helping people
that could already help themselves.

-- 
	Philip K.

Re: Interactive guide for new users

[Eli Zaretskii]

> From: "Philip K." <philipk@posteo.net>
> Date: Sat, 19 Sep 2020 19:16:33 +0200
> Cc: Göktuğ Kayaalp <self@gkayaalp.com>,
>  Yuan Fu <casouri@gmail.com>, Eli Zaretskii <eliz@gnu.org>,
>  Stefan Kangas <stefankangas@gmail.com>, emacs-devel <emacs-devel@gnu.org>
> 
> 
> An issue I can imagine is that a lot of the options that would be
> displayed in a wizard like this wouldn't mean too much to
> newcomers. "Helm" or "Ivy"? "Projectile"? Even Emacs-native packages are
> often confusing ("Hippie-Expand", "Xref", etc.). Without a way to test
> and find out what these options _mean_, you would only be helping people
> that could already help themselves.

The interactive guide is supposed to offer non-default options that
make Emacs UI more similar to what newcomers might expect.  It wasn't
supposed to offer loading large packages such as those which you name,
certainly not packages that are not bundled with Emacs.

But yes, deciding which options to offer and how to arrange them is
the hard part of this job.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hello Eli.

[...]

> The interactive guide is supposed to offer non-default options that
> make Emacs UI more similar to what newcomers might expect.  It wasn't
> supposed to offer loading large packages such as those which you name,
> certainly not packages that are not bundled with Emacs.

Certainly. That's why this is a rough draft of a vision.

If we agreed on the general vision it's perfectly possible to do as the
1st step (MVP in some modern parlance) only the "General editor
preferences" or the "Org-mode preferences". And even there, just a few
of them. 

> But yes, deciding which options to offer and how to arrange them is
> the hard part of this job.

The idea proposed here is:
1. distributions first, because they define the lot for themselves. If
any of them is chose, the wizard almost ends there.

2. General editor preferences (what was discussed previously in the
list). While we can define defaults, giving the options with clear
impact description allows the User to choose (or jump the decision and
leave the default). It makes much less sense to try to define the same
defaults for everyone, old wises and newbies alike. 

3. At last very last, other non-editing emacs big applications, like
mail and such. 

I totally agree that big modules (if they ever are included) should go
after general editor and/or org-mode preferences. Or, at least, should
be developed/scripted (included in the wizard) not as first stage. Emacs
comes first for the User benefit. b^.^d 

Another option, is not to select and install, but just to cite a few
things that we know people use, are powerful and can make a huge
difference, like magit, in the end.

This is proposed because many people doesn't even know they exist, and
just seeing the potential the whole integrated emacs ecosystem has,
gives much more impetus to make the effort to dive into Emacs. 

Best...

-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Eduardo Mercovich <eduardo@mercovich.net>
> Cc: "Philip K." <philipk@posteo.net>, self@gkayaalp.com, casouri@gmail.com,
>  stefankangas@gmail.com, emacs-devel@gnu.org
> Date: Sat, 19 Sep 2020 15:09:38 -0300
> 
> If we agreed on the general vision it's perfectly possible to do as the
> 1st step (MVP in some modern parlance) only the "General editor
> preferences" or the "Org-mode preferences". And even there, just a few
> of them. 

My advice is not try to bite a too large chunk of this -- the job is
not easy even without that.

> The idea proposed here is:
> 1. distributions first, because they define the lot for themselves. If
> any of them is chose, the wizard almost ends there.

I don't see any need to do this, certainly not as the first step.  If
someone wants one of those versions, they don't need us.

> 2. General editor preferences (what was discussed previously in the
> list). While we can define defaults, giving the options with clear
> impact description allows the User to choose (or jump the decision and
> leave the default). It makes much less sense to try to define the same
> defaults for everyone, old wises and newbies alike. 

My suggestion is to focus on this part alone.  Getting that right is
not easy, and if successful, will be a significant advancement, IMO.

> 3. At last very last, other non-editing emacs big applications, like
> mail and such. 

Suggest to drop this one for now as well.  Org mode as well.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hi.

>> If we agreed on the general vision it's perfectly possible to do as the
>> 1st step (MVP in some modern parlance) only the "General editor
>> preferences" or the "Org-mode preferences". And even there, just a few
>> of them. 

> My advice is not try to bite a too large chunk of this -- the job is
> not easy even without that.

Sure. It's just a vision, there is no commitment, just a bit of thought
to augment the probability of future integrity from an interaction
design perspective. :)

>> The idea proposed here is:
>> 1. distributions first [...]

> I don't see any need to do this, certainly not as the first step.  If
> someone wants one of those versions, they don't need us.

New users don't know they exist... we are only opening their eyes.
But of course, it can wait. 

>> 2. General editor preferences [...]

> My suggestion is to focus on this part alone.  Getting that right is
> not easy, and if successful, will be a significant advancement, IMO.

Perfect. Is it there any agreed upon list of things on this front?
If not, I can collect some from the list and maybe frequent questions
in reddit, SE and somewhere else...

>> 3. At last very last, other non-editing emacs big applications, like
>> mail and such. 

> Suggest to drop this one for now as well.  Org mode as well.

As before, we will start with the general editor.

Just as a check, do you agree that it is desirable to separate text and options
from the executable code? (sorry if my language is not appropriate,
please correct me as much as needed, I'm not a native English speaker). 

Because I'm trying a way to specify this in an org-mode file and it
would be great if we can modify the wizard particular text and options
without touching the code itself. 

Or maybe having this in a literate file, alternating both text and code (but
not mixed with UI text inside the code). 


-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Eduardo Mercovich <eduardo@mercovich.net>
> Cc: philipk@posteo.net, self@gkayaalp.com, casouri@gmail.com,
>  stefankangas@gmail.com, emacs-devel@gnu.org
> Date: Sat, 19 Sep 2020 18:43:15 -0300
> 
> >> 1. distributions first [...]
> 
> > I don't see any need to do this, certainly not as the first step.  If
> > someone wants one of those versions, they don't need us.
> 
> New users don't know they exist... we are only opening their eyes.

I think they already do know.  Moreover, I think they will decide to
try those before they get to see what you are planning to make happen.

> >> 2. General editor preferences [...]
> 
> > My suggestion is to focus on this part alone.  Getting that right is
> > not easy, and if successful, will be a significant advancement, IMO.
> 
> Perfect. Is it there any agreed upon list of things on this front?

Not only don't we have an agreed-upon list, we don't even have a
proposal for an exhaustive list.  I think the list will be quite long,
and if so, it will have to be subdivided into some groups; we don't
have any idea or suggestions for what those groups might be.

If we can come up with such a list, discuss it, agree on it, and have
a reasonable grouping (if needed), that would be a huge progress
towards making everything discussed here close to happening.

> Just as a check, do you agree that it is desirable to separate text and options
> from the executable code? (sorry if my language is not appropriate,
> please correct me as much as needed, I'm not a native English speaker). 

I don't think I understand what you mean by "text" and "executable
code" in this context.  If by "executable code" you mean the Lisp
program which implements the list of options and their presentation to
the user, then this can come later.  We need first to have the list of
options.  Once we have that, we can talk about how to present them,
and finally implement that.

> Or maybe having this in a literate file, alternating both text and code (but
> not mixed with UI text inside the code). 

The form is up to you.  The important part is to focus first on the
list of options, without distracting ourselves to aspects of code that
are not the primary goal at this first stage.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hi Eli.

[...]

>> >> 1. distributions first [...]

>> > I don't see any need to do this, certainly not as the first step. If
>> > someone wants one of those versions, they don't need us.
 
>> New users don't know they exist... we are only opening their eyes.

> I think they already do know.  Moreover, I think they will decide to
> try those before they get to see what you are planning to make happen.

Those things I prefer to measure them in an experiment. :)
Anyway, I totally agree that it's not our priority now.

 [...]

>> Perfect. Is it there any agreed upon list of things on this front?

> Not only don't we have an agreed-upon list, we don't even have a
> proposal for an exhaustive list. [...] If we can come up with such a
> list, discuss it, agree on it, and have a reasonable grouping (if
> needed), that would be a huge progress towards making everything
> discussed here close to happening. 

Then, since such a list seems valuable (before discussing the value of a
common vision), I propose a process to generate that list based on some
simple tested and working principles (*1): 

1- Let's collect a list of all the proposed preferences, by any member of
this list (to start). Everyone is invited to propose as many as it
wants. 

2- Then we prioritize with the same group (this list) by giving each
person a certain amount of points depending on the total amount of
preferences. It could range from 40% if they are few, to ~50% if they
are many, say, more than 20. Just as an example, if the total collected
options are 25 (since many people will agreed on some basic ones and
have a particular one to add, it could be bigger, of course) we may
give ~14 points to each person. 

3- Each person can cast it's points as it likes: all of them to 1
preference, 1 to each preference while it's points lasts, or any
combination in between. In the previous example, someone can put their
14 points to show-line-numbers, other to 14 different options (1 point
per option), and a third 5 to show-line-numbers, 6 to CUA-or-Emacs
cut-copy-paste, and 3 to show-menu-bar. 

4- We sum the total points per preference. Order from more to less
points. If they are few (say, less than a dozen), they can go all. If
they are too much, we can cut using any agreed upon criteria like a kind
of Pareto (66%~80% of the total points awarded) or other (the 1st N
items). 

If this seems ok to all of you, with this process we will have gone from
many persons with different opinions to a mostly agreed of the most
accepted (or desired) preferences to be set for the general editor
preferences. And it shouldn't take more than a few days at most (we have
to see what tool to use, since I assume that proprietary tools are not
acceptable; Limesurvey allows this, even if it's a bit oversized..). 

This process can be repeated for each "section" or group that we may
like (like org-mode or whatever you may find valuable after this). 

Now, after the list-making, we can make the screens (they don't have to
be functional) and test them with users as I commented on a previous mail. 

What do you think? 


(*1) From Sociocracy, maximize (democratize) input and optimize decision
making, plus the acceptable options range; from agile, let's try to have
something good enough working to validate our assumptions and learn from
reality before investing too much or taking too much time. 
-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Eduardo Mercovich <eduardo@mercovich.net>
> Cc: philipk@posteo.net, self@gkayaalp.com, casouri@gmail.com,
>  stefankangas@gmail.com, emacs-devel@gnu.org
> Date: Mon, 21 Sep 2020 19:15:38 -0300
> 
> 1- Let's collect a list of all the proposed preferences, by any member of
> this list (to start). Everyone is invited to propose as many as it
> wants. 

I suggest that you start the ball rolling by posting a list of options
you think we should consider (in a separate discussion topic, please).

Let's discuss how to filter and prioritize the options once we have a
provisional list and have an idea about its size.

Thanks.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hello Eli.

[...]

>> 1- Let's collect a list of all the proposed preferences, by any member of
>> this list (to start). Everyone is invited to propose as many as it
>> wants. 

> I suggest that you start the ball rolling by posting a list of options
> you think we should consider (in a separate discussion topic, please).

My area of expertise is not programming, so I can hardly propose what a
programmer may find useful to configure. I can only propose what I
-personally- find useful (and that list is already done).

And I believe this is true for many in the Emacs community; don't we
value Emacs incredible plasticity and ability to be adapted to each
person's way of thinking and doing? 

That's why I proposed a *process* to do it: we can all add our voices (all
that are interested, at least) and go forward together because we agreed
on how to do so. 

> Let's discuss how to filter and prioritize the options once we have a
> provisional list and have an idea about its size.

If we do this, we may make a list and then we will stop going forward to
discuss how to filter and prioritize. If we agreed on a process, then
it's all forward steps until the end of the proposed process (of course
anyone can stop and complain at any point, but the probability is
smaller and the rest still can go on while we see what happens). 

Up to now we were unable to do it in the usual way. I only bring another
proposal to proceed which is not mine at all, and has been used with
success in many other communities. 

In brief:

- We want to flatten a bit the learning wall for newcomers and
  make emacs more desirable for them, showing in can be not only
  powerful, but usable from the start and beautiful too.

- We agreed that a "wizard" (set of linear steps with clear options on
  each one) is positive to achieve that objective. 

- There is a proposal for a process to get a generally agreed list of
  variables to include in this wizard. 

- if you find this proposal inadequate please tell me so and I'll just
  add my personal variables and wait. I have no particular problem with
  that.

- But if you see no particular problem now with the proposed steps, I
  beg you to consider the possibility of giving it a try, going forward
  all together. In this case, I will start it in a separate thread and
  make the work to integrate everything as proposed. I will only ask
  about some details regarding tools to use for collaboration (and this
  could be done to the list or with a few people that can help this
  Emacs newbie in order not to make noise in the list).

In each -and any- way, thanks a lot for your kind attention and
understanding. 

Best regards...

-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Caio Henrique]

IMO the wizard/guide/tutorial for new users should have a section
dedicated to programming. When you open the programming section, you
would find a list of programming languages with some options like:

* C and C++
This adds syntax checking, jump to definition/declaration, function
documentation, autocompletion etc to C and C++.

** Requirements
- You need to install a language server like ccls or clangd on your
operating system.

** Options
[ ] Add flymake hook to C and C++ modes. This will enable syntax checking.
[ ] Install company from ELPA and add a hook to C and C++ modes. This
will enable a modern autocompletion framework.
[ ] Install eglot from ELPA and add a hook to C and C++ modes. This will
enable a LSP client with lots of features like completion via company,
code actions, type definitions, jump to definition etc.
[ ] Install yasnippet from ELPA and add a hook to C and C++ modes. This
will enable a code template system.

Cordially,
Caio Henrique

Re: Interactive guide for new users

[Eduardo Mercovich]

Olá Henrique.

> IMO the wizard/guide/tutorial for new users should have a section
> dedicated to programming. When you open the programming section, you
> would find a list of programming languages  [...]

I totally agree. That was the sectioning proposal in the activity
diagram, except that -being no programmer myself- I assumed it was in
general editor.

There should be a "languages" section. I totally support your idea. :)

-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Stefan Kangas]

Eduardo Mercovich <eduardo@mercovich.net> writes:

> - But if you see no particular problem now with the proposed steps, I
>   beg you to consider the possibility of giving it a try, going forward
>   all together. In this case, I will start it in a separate thread and
>   make the work to integrate everything as proposed.

FWIW, I think the proposed process sounds good.  Why not try it?  It
doesn't bind us to do anything in particular, and it seems to me that
Eduardo has experience in carrying out surveys like these.

Worst case, the information we collect is just not very useful and we
move on.  But I find it more likely that we would learn something
interesting.

Just my two cents.

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Eduardo Mercovich <eduardo@mercovich.net>
> Cc: philipk@posteo.net, self@gkayaalp.com, casouri@gmail.com,
>  stefankangas@gmail.com, emacs-devel@gnu.org
> Date: Wed, 23 Sep 2020 09:54:17 -0300
> 
> > I suggest that you start the ball rolling by posting a list of options
> > you think we should consider (in a separate discussion topic, please).
> 
> My area of expertise is not programming, so I can hardly propose what a
> programmer may find useful to configure. I can only propose what I
> -personally- find useful (and that list is already done).

I wouldn't be worried about that.  Just post the list you can come up
with, and others will chime in.

> That's why I proposed a *process* to do it: we can all add our voices (all
> that are interested, at least) and go forward together because we agreed
> on how to do so. 

IME, talking too much about the process runs the risk to leave the
discussion there.  Having a list to discuss makes the discussions much
more practical.

Thanks.

Re: Interactive guide for new users

[Yuan Fu]

> On Sep 23, 2020, at 10:58 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Eduardo Mercovich <eduardo@mercovich.net>
>> Cc: philipk@posteo.net, self@gkayaalp.com, casouri@gmail.com,
>> stefankangas@gmail.com, emacs-devel@gnu.org
>> Date: Wed, 23 Sep 2020 09:54:17 -0300
>> 
>>> I suggest that you start the ball rolling by posting a list of options
>>> you think we should consider (in a separate discussion topic, please).
>> 
>> My area of expertise is not programming, so I can hardly propose what a
>> programmer may find useful to configure. I can only propose what I
>> -personally- find useful (and that list is already done).
> 
> I wouldn't be worried about that.  Just post the list you can come up
> with, and others will chime in.
> 

I think a methodology that can produce a decision is helpful. IME people can’t converge on a result that no one opposes, and eventually everyone wore out and the discuss stalls.

>> That's why I proposed a *process* to do it: we can all add our voices (all
>> that are interested, at least) and go forward together because we agreed
>> on how to do so. 
> 
> IME, talking too much about the process runs the risk to leave the
> discussion there.  Having a list to discuss makes the discussions much
> more practical.
> 
> Thanks.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hello Yuan.

 [...]

>> I wouldn't be worried about that.  Just post the list you can come up
>> with, and others will chime in.

> I think a methodology that can produce a decision is helpful. IME
> people can’t converge on a result that no one opposes, and eventually
> everyone wore out and the discuss stalls.

Thanks a lot. That is my observation from reading the list too. 

>>> That's why I proposed a *process* to do it: we can all add our voices (all
>>> that are interested, at least) and go forward together because we agreed
>>> on how to do so. 

>> IME, talking too much about the process runs the risk to leave the
>> discussion there.  Having a list to discuss makes the discussions much
>> more practical.

Eli, the process doesn't seems to gather much discussion and a couple
people already liked it in public. It can be run just now if you say
yes, so there is no time wasted and a lot to gain if we can go forward
together with a common consensus. 

Please, let's try this approach and if it doesn't work, I promise I'll post my
personal list without a hitch. :)

-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Eli Zaretskii]

> From: Eduardo Mercovich <eduardo@mercovich.net>
> Cc: Eli Zaretskii <eliz@gnu.org>, philipk@posteo.net, Göktuğ Kayaalp
>  <self@gkayaalp.com>, Stefan Kangas <stefankangas@gmail.com>,
>  emacs-devel@gnu.org
> Date: Wed, 30 Sep 2020 10:20:03 -0300
> 
> >> IME, talking too much about the process runs the risk to leave the
> >> discussion there.  Having a list to discuss makes the discussions much
> >> more practical.
> 
> Eli, the process doesn't seems to gather much discussion and a couple
> people already liked it in public. It can be run just now if you say
> yes, so there is no time wasted and a lot to gain if we can go forward
> together with a common consensus. 
> 
> Please, let's try this approach and if it doesn't work, I promise I'll post my
> personal list without a hitch. :)

You don't need my permission: this is a public list, and anybody can
post anything as long as that's on-topic here.

I expressed my opinion, based on my experience, but don't let my
opinions stop you from doing what you think is right.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hi Philip, thanks for your kind and fast feedback. 

Sorry I replied to everyone in the thread, just wanted a slower jump
into this pond. It looks like I'm now completely in the water. :D

> An issue I can imagine is that a lot of the options that would be
> displayed in a wizard like this wouldn't mean too much to newcomers.
> [...] 

That's why a sample step/screen is included. The options are
(proposed to be) phrased in a way that could be understood without
knowing emacs.

I was actually doubting even to include in each a link to it's canonical
URL (I assume that it would be the one already in the package manager).

In the org-mode preferences "section" (let's call it that way because it
may have many steps) for example, leading stars should be explained (of
course, a screenshot would be the best):

--8<---------------cut here---------------start------------->8---

Org-mode defines heading hierarchy with asteriscs (stars) as the 1st character and arrange the left-alignment according to the heading level: 1 close to the left margin and other ones moving to the right.
Some people prefer to have a simpler visual display and use only the
alignment (and the font size and/or color) to show the heading hierarchy.

Please select your option: 

(1) Hide the leading stars

(2) Leave visible the leading stars

(9) I'd like to leave this step for now (you can always make it later).
(0) I want to stop this wizard now.
--8<---------------cut here---------------end--------------->8---

In this way, the User can always choose to stop, jump this option for
now, or take one of them. 

Also, there should be a way to go back (not included in this rough
draft).

> Without a way to test and find out what these options _mean_,
> you would only be helping people that could already help themselves.

Testing with users is one of my specialties, I would happily make a
testing protocol before making the design, tests and development. In a
way, it is like TDD, but with interaction design...

-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Interactive guide for new users

[Philip K.]

Eduardo Mercovich <eduardo@mercovich.net> writes:

> Hi Philip, thanks for your kind and fast feedback. 
>
> Sorry I replied to everyone in the thread, just wanted a slower jump
> into this pond. It looks like I'm now completely in the water. :D
>
>> An issue I can imagine is that a lot of the options that would be
>> displayed in a wizard like this wouldn't mean too much to newcomers.
>> [...] 
>
> That's why a sample step/screen is included. The options are
> (proposed to be) phrased in a way that could be understood without
> knowing emacs.
>
> I was actually doubting even to include in each a link to it's canonical
> URL (I assume that it would be the one already in the package manager).
>
> In the org-mode preferences "section" (let's call it that way because it
> may have many steps) for example, leading stars should be explained (of
> course, a screenshot would be the best):
>
> --8<---------------cut here---------------start------------->8---
>
> Org-mode defines heading hierarchy with asteriscs (stars) as the 1st character and arrange the left-alignment according to the heading level: 1 close to the left margin and other ones moving to the right.
> Some people prefer to have a simpler visual display and use only the
> alignment (and the font size and/or color) to show the heading hierarchy.
>
> Please select your option: 
>
> (1) Hide the leading stars
>
> (2) Leave visible the leading stars
>
> (9) I'd like to leave this step for now (you can always make it later).
> (0) I want to stop this wizard now.
> --8<---------------cut here---------------end--------------->8---
>
> In this way, the User can always choose to stop, jump this option for
> now, or take one of them. 
>
> Also, there should be a way to go back (not included in this rough
> draft).

Even with the ability to skip and go back, I still think that a total
newcomer won't be able to gain a lot from options like these. Maybe I'm
just bad, but in my case, I would skim over the text or wouldn't be too
interested in reading it in detail, to imagine what the differences
would be like. If anything, a visualisation would be needed. For example
in a separate window.

>> Without a way to test and find out what these options _mean_,
>> you would only be helping people that could already help themselves.
>
> Testing with users is one of my specialties, I would happily make a
> testing protocol before making the design, tests and development. In a
> way, it is like TDD, but with interaction design...

I'm not sure we're talking about the same testing here? I had more of a
"playground" like approach, where you can immediately or quickly see
what this option means, but I don't know if that's what you had in mind
too.

-- 
	Philip K.

Re: Interactive guide for new users

[Eduardo Mercovich]

Hi Philip.

 [...]

>> Also, there should be a way to go back (not included in this rough
>> draft).

> Even with the ability to skip and go back, I still think that a total
> newcomer won't be able to gain a lot from options like these. Maybe I'm
> just bad, but in my case, I would skim over the text or wouldn't be too
> interested in reading it in detail, to imagine what the differences
> would be like. If anything, a visualisation would be needed. For example
> in a separate window.

I may think or not like you, but in this case it doesn't matter so much
what we think, but rather what the expected users do.

So I propose we should measure it with a prototype and a usability test.

Than is, we don't need to really do it, just prototype (simulate) it and
observe some Users using it. After the test we can probe for the reasons
if the observed behaviour. 

[...]

>> Testing with users is one of my specialties, I would happily make a
>> testing protocol before making the design, tests and development. In a
>> way, it is like TDD, but with interaction design...

> I'm not sure we're talking about the same testing here? I had more of a
> "playground" like approach, where you can immediately or quickly see
> what this option means, but I don't know if that's what you had in mind
> too.

The test I had in mind is the traditional usability test: we draw (even
with text) the proposed screens, have people use them (a good sample
qualitatively speaking, 5 to 7 is good to start), clear criteria for
observations, and see what they understand and value from what they do. 

As was said before, in the post-tasks interview, we can go deeper to
understand what they understood and how they made their choices. 

Based on that, we can make our design (*1) choices. :)

Best...


(*1): design not as visual design, but as "a process that gives form". 
-- 
eduardo mercovich

 Donde se cruzan tus talentos 
 con las necesidades del mundo, 
 ahí está tu vocación. 
 (Anónimo)

Re: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Thu, 10 Sep 2020 19:20:34 -0400
> Cc: Göktuğ Kayaalp <self@gkayaalp.com>,
>  emacs-devel <emacs-devel@gnu.org>
> 
> > I don't think this scales.  Emacs has thousands of options, I'm
> > guessing hundreds of them are important for the audience you have in
> > mind.  You will get a huge set of many options that people with
> > "TL;DR" state of mind will never be able to review, let alone decide
> > what is for them.
> 
> I think there are a few configurations that a beginner would want to change right after he starts Emacs, usually very basic settings. If you think it’s a good idea, I can go to reddit and ask what people missed when then started using Emacs for the first few minutes. 

I think it could be a good idea to ask users, yes.  However, "for the
first few minutes" is not a good criterion, IMO: we want to provide a
facility for easily finding important options for users who already
use Emacs for weeks, maybe months.  The options "for the first few
minutes" are supposed to be on the Options menu already.

> > The grouping of the options must be based on some "themes" or similar,
> > to be useful.  The challenge is, of course, to come up with a useful
> > list of such "themes", and then decide which options should each theme
> > enable.
> 
> Others has described the out-of-the-box experience of doom Emacs, it seems to me that such job is better done by a “distribution” of Emacs than by vanilla Emacs.

"Better" in what sense?  What do the people who maintain Spacemacs or
DOOM know about Emacs that we don't?

> OTHO, vanilla Emacs could add a tiny guide like I proposed to more or less improve the life for those who started Emacs without reading any tutorial on the internet.

Sorry to be negative, but based on experience I have hard time
believing in such guides: people who are involved in Emacs development
are much better coding than writing good documentation, let alone
tutorial documentation for newbies.  Let's do what we do best: produce
features that make it easier to discover and turn on popular features.

Re: Gather a list of confusions beginner tend to have

[Dmitry Gutov]

On 11.09.2020 09:45, Eli Zaretskii wrote:
>> OTHO, vanilla Emacs could add a tiny guide like I proposed to more or less improve the life for those who started Emacs without reading any tutorial on the internet.
> Sorry to be negative, but based on experience I have hard time
> believing in such guides: people who are involved in Emacs development
> are much better coding than writing good documentation, let alone
> tutorial documentation for newbies.  Let's do what we do best: produce
> features that make it easier to discover and turn on popular features.

Perhaps we can nevertheless encourage "others" to contribute such guide(s)?

Re: Gather a list of confusions beginner tend to have

[Emanuel Berg via Emacs development discussions.]

Wait... what is so confusing about Emacs?

I don't remember reading anything and I also don't
remember anything that was so confusing about it.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Gather a list of confusions beginner tend to have

[Yuan Fu]

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

> 
> I think it could be a good idea to ask users, yes.  However, "for the
> first few minutes" is not a good criterion, IMO: we want to provide a
> facility for easily finding important options for users who already
> use Emacs for weeks, maybe months.  The options "for the first few
> minutes" are supposed to be on the Options menu already.
> 

I felt that people are most confused on the first few minutes of using Emacs, but I won’t argue this before asked for real experience on reddit.

>>> The grouping of the options must be based on some "themes" or similar,
>>> to be useful.  The challenge is, of course, to come up with a useful
>>> list of such "themes", and then decide which options should each theme
>>> enable.
>> 
>> Others has described the out-of-the-box experience of doom Emacs, it seems to me that such job is better done by a “distribution” of Emacs than by vanilla Emacs.
> 
> "Better" in what sense?  What do the people who maintain Spacemacs or
> DOOM know about Emacs that we don't?

They can do things we can’t. They can bundle MELPA packages, they can set various defaults, they can promote one package over another, they can bundle a bunch of helper commands and configurations.

> 
>> OTHO, vanilla Emacs could add a tiny guide like I proposed to more or less improve the life for those who started Emacs without reading any tutorial on the internet.
> 
> Sorry to be negative, but based on experience I have hard time
> believing in such guides: people who are involved in Emacs development
> are much better coding than writing good documentation, let alone
> tutorial documentation for newbies.  Let's do what we do best: produce
> features that make it easier to discover and turn on popular features.

I welcome such profile functionality, that will be very nice. In the mean time, a guide still has its place: how would a new user know he can choose a profile otherwise? You can add a menu button or a link on the slash screen, but I doubt if anything can beat a guide on discoverability. 

Not being good at writing tutorial for newbie is one thing, not doing it is another thing. If we want Emacs to be more newbie-friendly, we should have a friendly introduction built-in.

Yuan


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

Re: Gather a list of confusions beginner tend to have

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Fri, 11 Sep 2020 09:52:34 -0400
> Cc: self@gkayaalp.com,
>  emacs-devel@gnu.org
> 
>  Others has described the out-of-the-box experience of doom Emacs, it seems to me that such
>  job is better done by a “distribution” of Emacs than by vanilla Emacs.
> 
>  "Better" in what sense?  What do the people who maintain Spacemacs or
>  DOOM know about Emacs that we don't?
> 
> They can do things we can’t. They can bundle MELPA packages, they can set various defaults, they can
> promote one package over another, they can bundle a bunch of helper commands and configurations.

These are not obstacles we cannot negotiate if needed.  If we decide
some feature is important, we can talk to the respective developers
and ask them to clean them up for Emacs or for GNU ELPA.  Or we can
write our own implementations of those or similar features.

Maybe, even probably, we will never provide the full suite of what
Spacemacs or DOOM do, but even a small number of easily turned on
features could be a significant improvement.

> Not being good at writing tutorial for newbie is one thing, not doing it is another thing. If we want Emacs to be
> more newbie-friendly, we should have a friendly introduction built-in.

I didn't want to say I'm against writing guides.  If someone wants to
write such guides, by all means go ahead, and TIA.

Re: Gather a list of confusions beginner tend to have

[Stefan Monnier]

>> "Better" in what sense?  What do the people who maintain Spacemacs or
>> DOOM know about Emacs that we don't?
> They can do things we can’t. They can bundle MELPA packages, they can set
> various defaults, they can promote one package over another, they can bundle
> a bunch of helper commands and configurations.

Indeed, there are fundamentally two things they do that we don't:
- they bundle extra packages
- they don't have to accommodate all Emacs users (tho over time, they
  discover that they have to accommodate their own users when
  introducing changes ;-)

We could also bundle extra packages, actually.
We just currently decide not to.


        Stefan

Re: Gather a list of confusions beginner tend to have

[Nick Savage]

Göktuğ Kayaalp <self@gkayaalp.com> writes:

>> I think everybody would agree on attracting more people to use
>> Emacs—that means more blogs and help, more contributor, etc. And
>> people agree that Emacs isn’t as beginner-friendly as it could be. The
>> problem is what to improve, and how.
>
> Not necessarily.  Personally, I don’t see much benefit in trying to
> appeal users that have no background in coding whatsoever, and users who
> wouldn’t really benefit from what Emacs has to offer.
>

As someone who comes to the community with minimal background to coding,
I'd like to add a little bit of my experience and what attracted me to
Emacs in the first place:

I've probably been using Emacs for around ten years, but not very
seriously until very recently. I originally dabbled in coding a tiny bit
in high school and experimented with Emacs because it seemed cool. I
studied in the humanities in university, and I made more use of it as an editor and for LaTeX. LaTeX is not an uncommon thing for people in
academia to be using - I actually met someone in accounting who said he
uses it!

I'll admit I'm atypical and I wouldn't expect the average humanities
student or professor to be using Emacs, no matter what, but I think
Emacs has a lot of value for people outside programming, especially with org-mode.

The big hurdle I think for a lot of users is that Emacs is basically a
black box. I had no idea until very recently that CUA mode exist, which
could add value to users. I actually really like the idea of a
configuration wizard, as others have suggested, with some common options like that. It's probably
the least destructive in terms of environment since it doesn't actually
change any defaults and can provide new users with a "modern" experience
out of the box.

> The major problem is that someone who fiddled with Emacs now and
> couldn’t make use of it may think differently when a couple years later
> they have some knowledge of programming (not necessarily professionally)
> and some experience with other tools.
>
> Anecdotally, I’ve picked up and quit Emacs multiple times before I
> decided to stay with it.  And it’s been more than 6 years now that I’m
> using it for the good part of my computing.  What was puzzling and weird
> to me back then is useful and essential to me now.
>

This is probably a good point though too, on the other hand. Locking in
CUA mode early with a configuration might lead users to stick with it
long-term instead of maybe seeing the value the rest of the program has,
for better or for worse.

Re: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On 2020-09-09 05:01 +03, Nick Savage <nick@nicksavage.ca> wrote:
> Göktuğ Kayaalp <self@gkayaalp.com> writes:
> I'll admit I'm atypical and I wouldn't expect the average humanities
> student or professor to be using Emacs, no matter what, but I think
> Emacs has a lot of value for people outside programming, especially with org-mode.

I’ve (almost) never programmed professionally either. Currently doing an
MA in linguistics.

Emacs indeed has much value outside programming; potentially much more
value for me and probably you too.

But using Emacs without _any_ programming knowledge, or at any interest
in learning even the tiniest bit to manage an init.el is, IMHO, kind of
a dead end.  Because sooner or later you’ll need it.  And it’s very
easy, but sadly there’s a shortage of resources that make programming
what it is---a rudimentary task, yet another UI to your computer---and
teach it as such.

I’m kinda getting lost in my sentences.  What I want to say is, Emacs is
not all that useful if you don’t want to do _any_ programming, including
your init.el, which when you use, is programming.  There are quite solid
alternatives to Org mode that require no programming knowledge.  There’s
Notion, there’s Roam Research (albeit I’d rather not touch it), but also
a couple very capable open source outliners.  Chances are, a user that’s
completely disinterested in programming may make more use of these
software.  Similarly for LaTeX.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Re: Gather a list of confusions beginner tend to have

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

  > Anecdotally, I’ve picked up and quit Emacs multiple times before I
  > decided to stay with it.  And it’s been more than 6 years now that I’m
  > using it for the good part of my computing.  What was puzzling and weird
  > to me back then is useful and essential to me now.

I think this demonstrates that someone for whom Emacs can ondeed be useful
may be unable recognize its usefulness when trying it out.

I know it was long ago, but can you remember anything importantly
useful about Emacs that you didn't recognize in those first attempts?

Does anyone else have an idea what things those might be?

We might be able to figure out better ways of demonstrating them to
potential satisfied Emacsers.


-- 
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: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On 2020-09-10 05:36 +03, Richard Stallman <rms@gnu.org> wrote:
> I know it was long ago, but can you remember anything importantly
> useful about Emacs that you didn't recognize in those first attempts?

Indeed, tho let me try.  I don’t really recall exact things but I’ll
write out my pathway in a couple of paragraphs; maybe it’s a pattern
some people will recognise.

So I came to it as someone teaching himself programming, probably
sometime in 2012 or 2013.  But I must have been aware of it before,
given I’ve been using GNU/Linux since I was a kid.

I was basically editor hopping as I was trying to figure out programming
by myself, and in that timeframe used everything under the sun,
basically.  Emacs was particularly interesting as it was what ‘cool Lisp
hackers’ used.  But IIRC the first few times I was trying to use it more
like Vim, i.e. editor with extensions and an rc file.  For some reason,
probably because that cool kids factor, I stuck with Emacs for a while.

Then I worked a job as a Python dev for a month or so, around the end of
2013.  The colleagues made me switch to Vim because they had a pretty
decent Python setup, whereas my Emacs Python setup was nonexistent.  And
that stuck for a long while.  I built a 1.5kLoC vimrc (which I’ve
probably lost since...), and even wrote a couple plugins (one of which a
colourscheme which seems to still see some little use in the community).

When it clicked for me, what Emacs could indeed allow me to do, was
probably around some time in 2015.  By then I had moved on to pursue my
education in humanities, and needed to organise my notes, manage my
todos and agenda.  That’s when I came back to Emacs, IIRC.  Typed in a
ton of notes into Org mode format.  And I stuck with it from then on.

At some point between some time after my switching to Vim and and later
finally swithing to Emacs I must’ve read a lot, possibly through Hacker
News, about Emacs and Org mode, and gathered a more refined view of
what’s possible with these tools.  And I recall being very frustrated
with the ‘unix way’ because it was never as neat as people made it seem
to be: I was having a difficult time fitting things together, especially
for non-programming toils the switch to humanities brought about.  I
also should’ve first watched ‘A Tour of Acme’ by Russ Cox [1], and it’s
not an exaggeration to say it’s one of the most influential moments in
my life with computers.  It must have clicked for me soon after that
that I could make out of Emacs what I wanted: an ‘integrated computing
environment’ where I can make things work for me, and fine tune
everything at almost any depth, and do all that interactively.

That seems obvious to me today, but back in those few years it must’ve
been a puzzle for me how actually this kind of stuff happens, how people
could make more use of Emacs than just as a text editor or IDE.

Hopefully that’s not one long wall of text with a completely irrelevant
personal story.

[1] https://www.youtube.com/watch?v=dP1xVpMPn8M

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

RE: Gather a list of confusions beginner tend to have

[Drew Adams]

> > I know it was long ago, but can you remember anything importantly
> > useful about Emacs that you didn't recognize in those first attempts?
> 
> Indeed, tho let me try.  I don’t really recall exact things but I’ll
> write out my pathway in a couple of paragraphs; maybe it’s a pattern
> some people will recognise. ...

What you wrote is, IMO, quite helpful (and interesting).  Thx.

[You might consider a fun "humanities" project of
working on (yet another) Emacs tour/tutorial/video.
Sounds like you'd have something to offer in this
regard.  By "working" on, I mean anything from
coming up with something new to critiquing/improving
something that already exists.]
 

Re: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On 2020-09-10 20:28 +03, Drew Adams <drew.adams@oracle.com> wrote:
> What you wrote is, IMO, quite helpful (and interesting).  Thx.

Thanks for your nice words! I’m glad it was of any use!

> [You might consider a fun "humanities" project of
> working on (yet another) Emacs tour/tutorial/video.
> Sounds like you'd have something to offer in this
> regard.  By "working" on, I mean anything from
> coming up with something new to critiquing/improving
> something that already exists.]

That’s actually part of a long term project of mine: a Computing for
Social Sciences course because we increasingly rely on more than just
statistics within these fields, yet very little can operate a computer
properly for the life of theirs.  But I will try to come up with an
intro or overview of Emacs in the shorter term, maybe I do manage to
make some things clearer and more approachable for some folk, given
there might be some ‘aligned needs’.

W.r.t. critique of Emacs, I doubt my critique would be of any use,
because I’m fine with the status quo.  I’m learning the ways of ‘kids
these days’ along with you folks, really.



-- 
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

RE: Interactive guide for new users

[Drew Adams]

> > 2. disable tool-bar-mode
> 
> We have just established that [the tool bar]
> is important for newbies.

Without expressing a preference for the default
behavior here, let me ask whether it's true that
we've established that tool-bar on is important
for newbies.

Menu-bar, yes.  Or a hamburger-menu or whatever.
But tool-bar?  Have we really "established" that?

A menu-bar is quite helpful for discovery, which
is important.  We want users to discover features
and key bindings.  A tool-bar isn't so useful for
discovery, I think.

But again, that's not an opinion that we should
remove it by default.  I'm just questioning the
declaration that it's already (newly) established
that it should be shown by default.

RE: Interactive guide for new users

[Ihor Radchenko]

> But again, that's not an opinion that we should
> remove it by default.  I'm just questioning the
> declaration that it's already (newly) established
> that it should be shown by default.

For example, toolbar is used to help new users with interactive isearch.
It shows next/previous match buttons to help users, who don't know about
C-s/C-r. Moreover, it also provides buttons to show docstring and
provides tooltips about key bindings in isearch-mode-map.

Best,
Ihor

Drew Adams <drew.adams@oracle.com> writes:

>> > 2. disable tool-bar-mode
>> 
>> We have just established that [the tool bar]
>> is important for newbies.
>
> Without expressing a preference for the default
> behavior here, let me ask whether it's true that
> we've established that tool-bar on is important
> for newbies.
>
> Menu-bar, yes.  Or a hamburger-menu or whatever.
> But tool-bar?  Have we really "established" that?
>
> A menu-bar is quite helpful for discovery, which
> is important.  We want users to discover features
> and key bindings.  A tool-bar isn't so useful for
> discovery, I think.
>
> But again, that's not an opinion that we should
> remove it by default.  I'm just questioning the
> declaration that it's already (newly) established
> that it should be shown by default.

Re: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On Tue, 8 Sep 2020 15:30:56 -0400, Yuan Fu wrote:
> I generally agree with your point. However, what I have in mind is not
> changing defaults, but rather a configuration wizard, that can prompt
> user and let him select from Emacs binding vs CUA binding, Emacs undo
> vs simple undo/redo, themes, etc. I’ve seen such wizard in Intellj
> Idea, Spacemacs, etc. Something like (just an example):

That looks pretty reasonable to me.  Maybe it’d pop up if user does not
have a ‘user-init-file’, maybe with a prelude that asks "Hey, you don’t
have an init file, do you want to run the initial configuration wizard"?
Also, at the end, maybe redirect the user to a revised version of C-h t
that accomodates the preferences in the wizard.

IDK how relevant, but my observation is that most inexperienced users
are coming to Emacs for Org mode.  So maybe making https://orgmode.org
more informative for Emacs newbies could help too.  Maybe create a
couple ‘official’ video walkthroughs comparing these customisations
versus traditional Emacs way, pros and cons to each.

--
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427

Gather a list of confusions beginner tend to have

[Yuan Fu]

I think everybody would agree on attracting more people to use Emacs—that means more blogs and help, more contributor, etc. And people agree that Emacs isn’t as beginner-friendly as it could be. The problem is what to improve, and how.

As the first step, we should collect real experiences from real beginners: someone starts to use Emacs just recently (e.g., less than one year). Ask people around, ask people on the internet. I’ll post on reddit for some input. Can I use a title like “Emacs developers wants to know what confuses beginners in vanilla Emacs?”

Once we have an idea on what real beginners are complaining about, we can then try to improve them.

Yuan

Re: Gather a list of confusions beginner tend to have

[Jean Louis]

* Yuan Fu <casouri@gmail.com> [2020-09-08 13:28]:
> I think everybody would agree on attracting more people to use
> Emacs—that means more blogs and help, more contributor, etc. And
> people agree that Emacs isn’t as beginner-friendly as it could
> be. The problem is what to improve, and how.

I have office in Tanzania, in Geita town, and several staff members
came to our office and one task among others was preparation for
administrative works. People who got prepared in such are those who do
not have much experiences with computers in general and do not posses
computer themselves.

They have been given a task to go through Emacs Tutorial as to become
able to use Emacs to write text and respond to emails and to write
reports.

Each of them could complete the task with success, I speak of number
of people as around ten of them.

Several of them have been writing reports and one of them was
translating Swahili to English and vice versa by using Emacs.

Thus my very specific experience with these staff members as beginners
tells me that Emacs was very beginner friendly, especially due to fact
that the Tutorial and Help was there, and I never had a case that I
needed to explain directly something to those staff members, they have
provided reports and still do, and can use Emacs as text editor.

Jean

Re: Gather a list of confusions beginner tend to have

[tomas]

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

On Thu, Sep 10, 2020 at 02:51:09PM +0300, Jean Louis wrote:

[...]

> I have office in Tanzania [...]

Hey, thanks for that report!

Cheers
 - t

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

Re: Gather a list of confusions beginner tend to have

[Andreas Röhler]

On 08.09.20 19:28, Yuan Fu wrote:


Hi,

thanks bringing up that matter.

When deciding to start with Emacs the faculty to extend was key.

A difficulty I'm still facing from time to time is the missing type-info 
in function documentation strings. Need to know the type of arguments 
and also the return-type.

Cheers,

Andreas

Re: Gather a list of confusions beginner tend to have

[Robert Pluim]

>>>>> On Tue, 15 Sep 2020 09:11:34 +0200, Andreas Röhler <andreas.roehler@online.de> said:

    Andreas> On 08.09.20 19:28, Yuan Fu wrote:


    Andreas> Hi,

    Andreas> thanks bringing up that matter.

    Andreas> When deciding to start with Emacs the faculty to extend was key.

    Andreas> A difficulty I'm still facing from time to time is the missing
    Andreas> type-info in function documentation strings. Need to know the type of
    Andreas> arguments and also the return-type.

Is this something missing in Emacs, or is it that some documentation
strings donʼt tell you this? If the latter, point them out and we'll
try to fix them.

Robert

Re: Gather a list of confusions beginner tend to have

[Andreas Röhler]

On 15.09.20 10:21, Robert Pluim wrote:
>>>>>> On Tue, 15 Sep 2020 09:11:34 +0200, Andreas Röhler <andreas.roehler@online.de> said:
>      Andreas> On 08.09.20 19:28, Yuan Fu wrote:
>
>
>      Andreas> Hi,
>
>      Andreas> thanks bringing up that matter.
>
>      Andreas> When deciding to start with Emacs the faculty to extend was key.
>
>      Andreas> A difficulty I'm still facing from time to time is the missing
>      Andreas> type-info in function documentation strings. Need to know the type of
>      Andreas> arguments and also the return-type.
>
> Is this something missing in Emacs, or is it that some documentation
> strings donʼt tell you this? If the latter, point them out and we'll
> try to fix them.
>
> Robert


Well, it happens from time to time... Let's search for some example though:

in ange-ftp.el

defun ange-ftp-dired-compress-file (name)

it's not told if "name" should be delivered as string are just a 
(quoted?) symbol.

defun ange-ftp-load (file &optional noerror nomessage nosuffix)

Assume the optional args must be boolean,  but not hint so far.


If you grep for "&rest args", should appear some stuff where it's not 
told what kind of args are expected.

For example in widget.el

(defun define-widget (name class doc &rest args)

Thanks developing Emacs,

Andreas

Re: Gather a list of confusions beginner tend to have

[Robert Pluim]

>>>>> On Tue, 15 Sep 2020 12:13:27 +0200, Andreas Röhler <andreas.roehler@online.de> said:
    >> Is this something missing in Emacs, or is it that some documentation
    >> strings donʼt tell you this? If the latter, point them out and we'll
    >> try to fix them.
    >> 
    >> Robert


    Andreas> Well, it happens from time to time... Let's search for some example though:

    Andreas> in ange-ftp.el

    Andreas> defun ange-ftp-dired-compress-file (name)

    Andreas> it's not told if "name" should be delivered as string are just a
    Andreas> (quoted?) symbol.

I think emacs always uses strings when naming files.

    Andreas> defun ange-ftp-load (file &optional noerror nomessage nosuffix)

    Andreas> Assume the optional args must be boolean,  but not hint so far.

Hmm yes, but I think thatʼs an internal function, so not too
surprising.

    Andreas> If you grep for "&rest args", should appear some stuff where it's not
    Andreas> told what kind of args are expected.

    Andreas> For example in widget.el

    Andreas> (defun define-widget (name class doc &rest args)

Are here it depends very much on which widget youʼre using, so itʼs
hard to specify in the docstring.

Robert

Re: Gather a list of confusions beginner tend to have

[Göktuğ Kayaalp]

On 2020-09-15 11:21 +03, Robert Pluim <rpluim@gmail.com> wrote:
> Is this something missing in Emacs, or is it that some documentation
> strings donʼt tell you this? If the latter, point them out and we'll
> try to fix them.

Don’t have examples handy but I do find myself perplexed as to pass in a
symbol or a string at times.  Even if both is okay, IMHO it’s nice
practice to express that precisely.

But also it’d be real cool if we had gradual typing in Emacs, e.g. some
‘declare-type’ function that can assign type info to symbols which can
they be used for static checks and docstrings.

We already do something similar in spirit with defcustoms, don’t we?

-- 
İ. Göktuğ Kayaalp / @cadadr / <https://www.gkayaalp.com/>
pgp:   024C 30DD 597D 142B 49AC 40EB 465C D949 B101 2427