Re: Interactive guide for new users

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

[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

[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

[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

[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

[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

[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

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

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

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

[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

[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

[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

[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

[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

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

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

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

[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

[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

[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

[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

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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

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

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

[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

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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[Itai Efrat]

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

I think that "Emacs Framework" (proposed by tec@tecosaur.com) is the best
term i've come across so far. It encapsulates the fact that although none
of these are distributing emacs in any sense, they are usually more than
configurations or starter packs. I can't speak for all of them, but Doom
Emacs and Spacemacs both provide abstractions when it comes to configuring
emacs, most notably their module and layer systems, which other than
providing a friendly starting point for using and configuring emacs also
provide a sort of meta structure to allow the user to more easily customise
what e.g. "Emacs when editing Haskell" is (At least in the case of Doom,
I'm unfamiliar with how user defined layers work in spacemacs but I imagine
they exist in a similar way to user defined modules in Doom Emacs).

Itai

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

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.