Emacs Newbie Info Pages

Emacs Newbie Info Pages

[Summer Emacs]

Hi everyone,

I posted a question in Reddit this morning about having an Emacs newbie info pages on the front of the default Emacs page for complete newbies and first-timers. I know that the splash page already has information links, which are very appreciated, but I think that first time users would be overwhelmed with the information and how to use it. The goal of this project would be the following:

1) A very visible (easy to see, and hard to miss) link at the top which says something like “New to Emacs? Click here!”
2) A simple “one page” info page with some general information about Emacs and suggested setups. This would include:

a) The link to the Emacs movement/editing tutorial (vital) and why it is necessary to go through it.
b) A quick overview for non-coders/devs on how Emacs is special and can be made to look like anything they want it to look like.
c) An explanation of how to configure Emacs in a basic way with a few links to some suggested configs to get started “out of the box” (I know this is contentious, please don’t bite my head off)
d) How they can download themes right away with some examples of some basic themes and links to some popular theme packages.
e) An explanation of some bigger packages which they might be interested in as non-coders (mostly writers or other office jobs) such as: Org-Mode, EWS, Denote, Org-Roam, Fontaine, etc…a quick explanation of what each one does, a link to the page where the information can be found.
f) How to use the configuration panels if they choose to go that route with a few quick examples for them to try out.

Now, a few things:
1) I’m not a dev. This is just my take from a non-dev perspective.
2) I’ve heard there was work on a wizard setup a while back but that it never went anywhere. My suggestion is to use the info pages instead of a wizard, but to make a newbie “home base” for new users which won’t overwhelm them. I’ve already written about 3 pages but it is very rough and needs a lot of work, links put in, and a lot of editing because my tone is very different from the tone of the manuals. I’ve never written a tutorial before, so I’m going to need some volunteers to help me with some of this stuff.
3) I don’t know what it takes to include such a thing into Emacs proper. I don’t know how to patch things, or know what the specifics are for submitting things in a proper way. Please don’t hold that against me - I’m willing to learn.

I wanted to write this email to put something concrete down rather than just say “Emacs needs to be better for newbs” and not do anything about it. Somebody suggest that I actually do, so I’m going to try.

I also don’t know if long emails are verboten here, so please excuse the length of this email. I”m used to writing large business projects and proposals where a few pages in length isn’t really much of an issue.

The reason I’m doing this:
I love Emacs, but I’m a special case and I know it. It was a sleepless week of learning how computer hard drives and what a CLI was during the lockdown of the pandemic eventually led me to Emacs. By then, I wasn’t put off as much by the initial welcome screen., But I know that many others might be. I’m not suggesting we change the welcome screen because I know that’s an issue which causes fights and division in the group - I’m just suggesting we have an area that is instantly accessible to allow users to see something that Emacs *could* be if they just learn a little bit. I hope that this is an acceptable and practical suggestion which does not reach for the stars but is more down to earth.

Thank you everyone who made it through this lengthy Email and I look forward to hearing from anyone with helpful suggestions, comments, and/or help.

Summer Emacs.

Re: Emacs Newbie Info Pages

[Philip Kaludercic]

Summer Emacs <summeremacs@summerstar.me> writes:

> Hi everyone,
>
> I posted a question in Reddit this morning about having an Emacs
> newbie info pages on the front of the default Emacs page for complete
> newbies and first-timers. I know that the splash page already has
> information links, which are very appreciated, but I think that first
> time users would be overwhelmed with the information and how to use
> it. The goal of this project would be the following:
>
> 1) A very visible (easy to see, and hard to miss) link at the top
> which says something like “New to Emacs? Click here!”
> 2) A simple “one page” info page with some general information about
> Emacs and suggested setups. This would include:

Any reason for it being a "one page" (i.e. one section) page?  Why use
Info, instead of a Help buffer?

>
> a) The link to the Emacs movement/editing tutorial (vital) and why it
> is necessary to go through it.
> b) A quick overview for non-coders/devs on how Emacs is special and
> can be made to look like anything they want it to look like.
> c) An explanation of how to configure Emacs in a basic way with a few
> links to some suggested configs to get started “out of the box” (I
> know this is contentious, please don’t bite my head off)

I think mentioning common configuration patterns, that might include
use-package, would be more useful than pointing people to personal
configurations.

> d) How they can download themes right away with some examples of some
> basic themes and links to some popular theme packages.
> e) An explanation of some bigger packages which they might be
> interested in as non-coders (mostly writers or other office jobs) such
> as: Org-Mode, EWS, Denote, Org-Roam, Fontaine, etc…a quick explanation

What is EWS?

> of what each one does, a link to the page where the information can be
> found.
> f) How to use the configuration panels if they choose to go that route
> with a few quick examples for them to try out.
>
> Now, a few things:
> 1) I’m not a dev. This is just my take from a non-dev perspective.
> 2) I’ve heard there was work on a wizard setup a while back but that
> it never went anywhere. 

There was a discussion a few years back, because of which I wrote and
continue to operate https://emacs.amodernist.com/?  The people who know
of it seem to like it.  It is not inside Emacs, but it's a M-x eww away.

>                         My suggestion is to use the info pages instead
> of a wizard, but to make a newbie “home base” for new users which
> won’t overwhelm them. I’ve already written about 3 pages but it is
> very rough and needs a lot of work, links put in, and a lot of editing
> because my tone is very different from the tone of the manuals. I’ve
> never written a tutorial before, so I’m going to need some volunteers
> to help me with some of this stuff.
> 3) I don’t know what it takes to include such a thing into Emacs
> proper. I don’t know how to patch things, or know what the specifics
> are for submitting things in a proper way. Please don’t hold that
> against me - I’m willing to learn.

If you can write Elisp, you can try to prepare a package as an initial
draft that we could first add to GNU ELPA, then move to the core when it
is mature enough.  Ping me if you have anything you want to submit.

> I wanted to write this email to put something concrete down rather
> than just say “Emacs needs to be better for newbs” and not do anything
> about it. Somebody suggest that I actually do, so I’m going to try.
>
> I also don’t know if long emails are verboten here, so please excuse
> the length of this email. I”m used to writing large business projects
> and proposals where a few pages in length isn’t really much of an
> issue.

This is certainly not the longest email I have seen here ^^

> The reason I’m doing this:
> I love Emacs, but I’m a special case and I know it. It was a sleepless
> week of learning how computer hard drives and what a CLI was during
> the lockdown of the pandemic eventually led me to Emacs. By then, I
> wasn’t put off as much by the initial welcome screen., But I know that
> many others might be. I’m not suggesting we change the welcome screen
> because I know that’s an issue which causes fights and division in the
> group - I’m just suggesting we have an area that is instantly
> accessible to allow users to see something that Emacs *could* be if
> they just learn a little bit. I hope that this is an acceptable and
> practical suggestion which does not reach for the stars but is more
> down to earth.
>
> Thank you everyone who made it through this lengthy Email and I look
> forward to hearing from anyone with helpful suggestions, comments,
> and/or help.
>
> Summer Emacs.

-- 
	Philip Kaludercic on siskin

Re: Emacs Newbie Info Pages

[Summer Emacs]

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


> On Sep 12, 2024, at 20:26, Philip Kaludercic <philipk@posteo.net> wrote:
> 
> Summer Emacs <summeremacs@summerstar.me <mailto:summeremacs@summerstar.me>> writes:
> 
>> Hi everyone,
>> 
>> I posted a question in Reddit this morning about having an Emacs
>> newbie info pages on the front of the default Emacs page for complete
>> newbies and first-timers. I know that the splash page already has
>> information links, which are very appreciated, but I think that first
>> time users would be overwhelmed with the information and how to use
>> it. The goal of this project would be the following:
>> 
>> 1) A very visible (easy to see, and hard to miss) link at the top
>> which says something like “New to Emacs? Click here!”
>> 2) A simple “one page” info page with some general information about
>> Emacs and suggested setups. This would include:
> 
> Any reason for it being a "one page" (i.e. one section) page?  Why use
> Info, instead of a Help buffer?

Good question: The “one page” I’m envisioning is like another default splash page with links to the various sections and an easy return point (such as M-x newbie).

>> a) The link to the Emacs movement/editing tutorial (vital) and why it
>> is necessary to go through it.
>> b) A quick overview for non-coders/devs on how Emacs is special and
>> can be made to look like anything they want it to look like.
>> c) An explanation of how to configure Emacs in a basic way with a few
>> links to some suggested configs to get started “out of the box” (I
>> know this is contentious, please don’t bite my head off)
> 
> I think mentioning common configuration patterns, that might include
> use-package, would be more useful than pointing people to personal
> configurations.

I think some examples would be a good idea. You may not realize this but if I throw a (setq ) in the face of a newbie with little explanation, we might never see them again. My suggestion would be to include some bare-bones configs with lots of comments and what everything means, including the comments.

>> d) How they can download themes right away with some examples of some
>> basic themes and links to some popular theme packages.
>> e) An explanation of some bigger packages which they might be
>> interested in as non-coders (mostly writers or other office jobs) such
>> as: Org-Mode, EWS, Denote, Org-Roam, Fontaine, etc…a quick explanation
> 
> What is EWS?

Emacs Writing Studio. Just released.https://github.com/pprevos/emacs-writing-studio

>> of what each one does, a link to the page where the information can be
>> found.
>> f) How to use the configuration panels if they choose to go that route
>> with a few quick examples for them to try out.
>> 
>> Now, a few things:
>> 1) I’m not a dev. This is just my take from a non-dev perspective.
>> 2) I’ve heard there was work on a wizard setup a while back but that
>> it never went anywhere. 
> 
> There was a discussion a few years back, because of which I wrote and
> continue to operate https://emacs.amodernist.com/?  The people who know
> of it seem to like it.  It is not inside Emacs, but it's a M-x eww away.

You have to get a newbie to understand what M-x eww is. “Just RTFM” isn’t the same anymore. Veronica just did a video on how “The Manual” has changed over the years: https://www.youtube.com/watch?v=4lUiUQOvRHQ (this should be required viewing for anyone writing help files today - they even used to explain what the space bar is used for.) My point is: Emacs, while powerful, while understandable by those with a modicum of time and maybe a slight bit of computer experience, is not newbie friendly. I’m not aiming to hold the hands of developers who are used to looking up functions on the fly; I’m proposing we have a page with sub-pages of easily understood material for non-developers and coders. I also am not proposing that we “change” Emacs in any way - I love Emacs the way it is. It’s just want an instantly available newbie section. It’s not a huge ask, right? =)

> 
>>                        My suggestion is to use the info pages instead
>> of a wizard, but to make a newbie “home base” for new users which
>> won’t overwhelm them. I’ve already written about 3 pages but it is
>> very rough and needs a lot of work, links put in, and a lot of editing
>> because my tone is very different from the tone of the manuals. I’ve
>> never written a tutorial before, so I’m going to need some volunteers
>> to help me with some of this stuff.
>> 3) I don’t know what it takes to include such a thing into Emacs
>> proper. I don’t know how to patch things, or know what the specifics
>> are for submitting things in a proper way. Please don’t hold that
>> against me - I’m willing to learn.
> 
> If you can write Elisp, you can try to prepare a package as an initial
> draft that we could first add to GNU ELPA, then move to the core when it
> is mature enough.  Ping me if you have anything you want to submit.

I’ve been learning Common Lisp in between learning calculus to prepare for physics courses, as well as working full time and traveling as a personal assistant. Also, I have a very active social life. I’ll get to elisp when I have time. =)

> 
>> I wanted to write this email to put something concrete down rather
>> than just say “Emacs needs to be better for newbs” and not do anything
>> about it. Somebody suggest that I actually do, so I’m going to try.
>> 
>> I also don’t know if long emails are verboten here, so please excuse
>> the length of this email. I”m used to writing large business projects
>> and proposals where a few pages in length isn’t really much of an
>> issue.
> 
> This is certainly not the longest email I have seen here ^^

That’s good to know! Ty. =)

>> The reason I’m doing this:
>> I love Emacs, but I’m a special case and I know it. It was a sleepless
>> week of learning how computer hard drives and what a CLI was during
>> the lockdown of the pandemic eventually led me to Emacs. By then, I
>> wasn’t put off as much by the initial welcome screen., But I know that
>> many others might be. I’m not suggesting we change the welcome screen
>> because I know that’s an issue which causes fights and division in the
>> group - I’m just suggesting we have an area that is instantly
>> accessible to allow users to see something that Emacs *could* be if
>> they just learn a little bit. I hope that this is an acceptable and
>> practical suggestion which does not reach for the stars but is more
>> down to earth.
>> 
>> Thank you everyone who made it through this lengthy Email and I look
>> forward to hearing from anyone with helpful suggestions, comments,
>> and/or help.
>> 
>> Summer Emacs.
> 
> -- 
> 	Philip Kaludercic on siskin

Summer Emacs.


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

Re: Emacs Newbie Info Pages

[Philip Kaludercic]

(Friendly reminder: Please don't forget to CC everyone when responding,
otherwise some people might miss your response!)

Summer Emacs <summeremacs@summerstar.me> writes:

>> On Sep 12, 2024, at 20:26, Philip Kaludercic <philipk@posteo.net> wrote:
>> 
>> Summer Emacs <summeremacs@summerstar.me
>> <mailto:summeremacs@summerstar.me>> writes:
>> 
>>> Hi everyone,
>>> 
>>> I posted a question in Reddit this morning about having an Emacs
>>> newbie info pages on the front of the default Emacs page for complete
>>> newbies and first-timers. I know that the splash page already has
>>> information links, which are very appreciated, but I think that first
>>> time users would be overwhelmed with the information and how to use
>>> it. The goal of this project would be the following:
>>> 
>>> 1) A very visible (easy to see, and hard to miss) link at the top
>>> which says something like “New to Emacs? Click here!”
>>> 2) A simple “one page” info page with some general information about
>>> Emacs and suggested setups. This would include:
>> 
>> Any reason for it being a "one page" (i.e. one section) page?  Why use
>> Info, instead of a Help buffer?
>
> Good question: The “one page” I’m envisioning is like another default
> splash page with links to the various sections and an easy return
> point (such as M-x newbie).

My point is just that if it is not a manual, with a table of contents,
an index, etc. then there might not be much of a point in using Info.  A
M-x newbie command that populates a help buffer might be just as useful,
and easier to maintain.

>>> a) The link to the Emacs movement/editing tutorial (vital) and why it
>>> is necessary to go through it.
>>> b) A quick overview for non-coders/devs on how Emacs is special and
>>> can be made to look like anything they want it to look like.
>>> c) An explanation of how to configure Emacs in a basic way with a few
>>> links to some suggested configs to get started “out of the box” (I
>>> know this is contentious, please don’t bite my head off)
>> 
>> I think mentioning common configuration patterns, that might include
>> use-package, would be more useful than pointing people to personal
>> configurations.
>
> I think some examples would be a good idea. You may not realize this
> but if I throw a (setq ) in the face of a newbie with little
> explanation, we might never see them again. My suggestion would be to
> include some bare-bones configs with lots of comments and what
> everything means, including the comments.

I guess we are thinking of different kinds of newbies here.  That being
said, an experiment I have been thinking about but haven't implemented
yet is a .ini-parser for Emacs that could load a Emacs configuration
from a file like 

--8<---------------cut here---------------start------------->8---
[package avy]
set all-windows all-frames
bind C-z avy-goto-word-1

[package auctex]
set TeX-master dwim
hook TeX-language-de-hook site/use-german
rebind RET newline 

[package bash-completion]
(bash-completion-setup)
--8<---------------cut here---------------end--------------->8---

where the common patterns are simplified and made safe (e.g. the "set"
directive wouldn't evaluate) but still remains powerful, as you can
intersperse lisp code.  If I ever get around to finishing this -- or
anyone else decides to steal the idea ;) -- then adding this to the core
and loading ~/.emacs.d/init.conf if it exists might be a useful thing to
mention in a newbie manual.

>>> d) How they can download themes right away with some examples of some
>>> basic themes and links to some popular theme packages.
>>> e) An explanation of some bigger packages which they might be
>>> interested in as non-coders (mostly writers or other office jobs) such
>>> as: Org-Mode, EWS, Denote, Org-Roam, Fontaine, etc…a quick explanation
>> 
>> What is EWS?
>
> Emacs Writing Studio. Just
> released.https://github.com/pprevos/emacs-writing-studio

ack.

>>> of what each one does, a link to the page where the information can be
>>> found.
>>> f) How to use the configuration panels if they choose to go that route
>>> with a few quick examples for them to try out.
>>> 
>>> Now, a few things:
>>> 1) I’m not a dev. This is just my take from a non-dev perspective.
>>> 2) I’ve heard there was work on a wizard setup a while back but that
>>> it never went anywhere. 
>> 
>> There was a discussion a few years back, because of which I wrote and
>> continue to operate https://emacs.amodernist.com/?  The people who know
>> of it seem to like it.  It is not inside Emacs, but it's a M-x eww away.
>
> You have to get a newbie to understand what M-x eww is. “Just RTFM”
> isn’t the same anymore. Veronica just did a video on how “The Manual”
> has changed over the years:
> https://www.youtube.com/watch?v=4lUiUQOvRHQ (this should be required
> viewing for anyone writing help files today - they even used to
> explain what the space bar is used for.) My point is: Emacs, while
> powerful, while understandable by those with a modicum of time and
> maybe a slight bit of computer experience, is not newbie friendly. I’m
> not aiming to hold the hands of developers who are used to looking up
> functions on the fly; I’m proposing we have a page with sub-pages of
> easily understood material for non-developers and coders. I also am
> not proposing that we “change” Emacs in any way - I love Emacs the way
> it is. It’s just want an instantly available newbie section. It’s not
> a huge ask, right? =)

I am not disagreeing, I just want to qualify this with my own impression
that a big problem nowadays is that people just don't want to read, no
matter what you write.  An indication for this might be that when I
tried out VSCode a few months ago, and I tried to open up a manual to
study the program properly, all I could find was a series of videos with
some light commentary.  And I suspect most people don't even watch them?

>> 
>>>                        My suggestion is to use the info pages instead
>>> of a wizard, but to make a newbie “home base” for new users which
>>> won’t overwhelm them. I’ve already written about 3 pages but it is
>>> very rough and needs a lot of work, links put in, and a lot of editing
>>> because my tone is very different from the tone of the manuals. I’ve
>>> never written a tutorial before, so I’m going to need some volunteers
>>> to help me with some of this stuff.
>>> 3) I don’t know what it takes to include such a thing into Emacs
>>> proper. I don’t know how to patch things, or know what the specifics
>>> are for submitting things in a proper way. Please don’t hold that
>>> against me - I’m willing to learn.
>> 
>> If you can write Elisp, you can try to prepare a package as an initial
>> draft that we could first add to GNU ELPA, then move to the core when it
>> is mature enough.  Ping me if you have anything you want to submit.
>
> I’ve been learning Common Lisp in between learning calculus to prepare
> for physics courses, as well as working full time and traveling as a
> personal assistant. Also, I have a very active social life. I’ll get
> to elisp when I have time. =)

Common Lisp is a good foundation for Elisp, certainly helped me.  But
otherwise no pressure, I think that almost everyone is familiar with
having things going on besides Emacs.

>> 
>>> I wanted to write this email to put something concrete down rather
>>> than just say “Emacs needs to be better for newbs” and not do anything
>>> about it. Somebody suggest that I actually do, so I’m going to try.
>>> 
>>> I also don’t know if long emails are verboten here, so please excuse
>>> the length of this email. I”m used to writing large business projects
>>> and proposals where a few pages in length isn’t really much of an
>>> issue.
>> 
>> This is certainly not the longest email I have seen here ^^
>
> That’s good to know! Ty. =)
>
>>> The reason I’m doing this:
>>> I love Emacs, but I’m a special case and I know it. It was a sleepless
>>> week of learning how computer hard drives and what a CLI was during
>>> the lockdown of the pandemic eventually led me to Emacs. By then, I
>>> wasn’t put off as much by the initial welcome screen., But I know that
>>> many others might be. I’m not suggesting we change the welcome screen
>>> because I know that’s an issue which causes fights and division in the
>>> group - I’m just suggesting we have an area that is instantly
>>> accessible to allow users to see something that Emacs *could* be if
>>> they just learn a little bit. I hope that this is an acceptable and
>>> practical suggestion which does not reach for the stars but is more
>>> down to earth.
>>> 
>>> Thank you everyone who made it through this lengthy Email and I look
>>> forward to hearing from anyone with helpful suggestions, comments,
>>> and/or help.
>>> 
>>> Summer Emacs.
>> 
>> -- 
>> 	Philip Kaludercic on siskin
>
> Summer Emacs.
>

-- 
	Philip Kaludercic on siskin

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Thu, 12 Sep 2024 19:17:51 +0000
> 
> I guess we are thinking of different kinds of newbies here.  That being
> said, an experiment I have been thinking about but haven't implemented
> yet is a .ini-parser for Emacs that could load a Emacs configuration
> from a file like 
> 
> --8<---------------cut here---------------start------------->8---
> [package avy]
> set all-windows all-frames
> bind C-z avy-goto-word-1
> 
> [package auctex]
> set TeX-master dwim
> hook TeX-language-de-hook site/use-german
> rebind RET newline 
> 
> [package bash-completion]
> (bash-completion-setup)
> --8<---------------cut here---------------end--------------->8---
> 
> where the common patterns are simplified and made safe (e.g. the "set"
> directive wouldn't evaluate) but still remains powerful, as you can
> intersperse lisp code.  If I ever get around to finishing this -- or
> anyone else decides to steal the idea ;) -- then adding this to the core
> and loading ~/.emacs.d/init.conf if it exists might be a useful thing to
> mention in a newbie manual.

This sounds like a new DSL to specify Emacs features to turn on and
off?  Is adding yet another extension language to Emacs is a good
idea?  If anything, why not start from Editorconfig way whose support
was recently added to Emacs -- that at least is a DSL known to others
out there?

Re: Emacs Newbie Info Pages

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Thu, 12 Sep 2024 19:17:51 +0000
>> 
>> I guess we are thinking of different kinds of newbies here.  That being
>> said, an experiment I have been thinking about but haven't implemented
>> yet is a .ini-parser for Emacs that could load a Emacs configuration
>> from a file like 
>> 
>> --8<---------------cut here---------------start------------->8---
>> [package avy]
>> set all-windows all-frames
>> bind C-z avy-goto-word-1
>> 
>> [package auctex]
>> set TeX-master dwim
>> hook TeX-language-de-hook site/use-german
>> rebind RET newline 
>> 
>> [package bash-completion]
>> (bash-completion-setup)
>> --8<---------------cut here---------------end--------------->8---
>> 
>> where the common patterns are simplified and made safe (e.g. the "set"
>> directive wouldn't evaluate) but still remains powerful, as you can
>> intersperse lisp code.  If I ever get around to finishing this -- or
>> anyone else decides to steal the idea ;) -- then adding this to the core
>> and loading ~/.emacs.d/init.conf if it exists might be a useful thing to
>> mention in a newbie manual.
>
> This sounds like a new DSL to specify Emacs features to turn on and
> off?  Is adding yet another extension language to Emacs is a good
> idea?  If anything, why not start from Editorconfig way whose support
> was recently added to Emacs -- that at least is a DSL known to others
> out there?

Yeah, a DSL with a castrated syntax that many users might be familiar
with.  It might be possible to reuse the EditorConfig parser, but not
much more beyond that.  As I said, I haven't finished my prototype yet,
so there isn't much of a point in discussing concrete questions yet, I
just wanted to bring it up as an idea.

-- 
	Philip Kaludercic on siskin

Re: Emacs Newbie Info Pages

[Summer Emacs]

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



> On Sep 12, 2024, at 21:17, Philip Kaludercic <philipk@posteo.net> wrote:
> 
> (Friendly reminder: Please don't forget to CC everyone when responding,
> otherwise some people might miss your response!)

Thanks. I’ll do that. =)

>> Good question: The “one page” I’m envisioning is like another default
>> splash page with links to the various sections and an easy return
>> point (such as M-x newbie).
> 
> My point is just that if it is not a manual, with a table of contents,
> an index, etc. then there might not be much of a point in using Info.  A
> M-x newbie command that populates a help buffer might be just as useful,
> and easier to maintain.

Okay. I didn’t know there was a difference but sure. (See, not a dev. Thank you for clearing that up =) )

>> I think some examples would be a good idea. You may not realize this
>> but if I throw a (setq ) in the face of a newbie with little
>> explanation, we might never see them again. My suggestion would be to
>> include some bare-bones configs with lots of comments and what
>> everything means, including the comments.
> 
> I guess we are thinking of different kinds of newbies here.  That being
> said, an experiment I have been thinking about but haven't implemented
> yet is a .ini-parser for Emacs that could load a Emacs configuration
> from a file like 
> 
> --8<---------------cut here---------------start------------->8---
> [package avy]
> set all-windows all-frames
> bind C-z avy-goto-word-1
> 
> [package auctex]
> set TeX-master dwim
> hook TeX-language-de-hook site/use-german
> rebind RET newline 
> 
> [package bash-completion]
> (bash-completion-setup)
> --8<---------------cut here---------------end--------------->8---
> 
> where the common patterns are simplified and made safe (e.g. the "set"
> directive wouldn't evaluate) but still remains powerful, as you can
> intersperse lisp code.  If I ever get around to finishing this -- or
> anyone else decides to steal the idea ;) -- then adding this to the core
> and loading ~/.emacs.d/init.conf if it exists might be a useful thing to
> mention in a newbie manual.

Well, since I keep hearing “Emacs is for everyone” and “Free software is for everyone”, I’m imagining some of my friends: people who use their phones and iPads, Tik Tok, iMessage, WhatsApp, and who don’t ever look at a computer unless they have to at work or in class. People like me who didn’t know how to do much of anything other than open a file, write in it, click a few buttons, and send it off in an Email. Those people. Regular people. People who don’t know what a function or a variable is. People who don’t know what a computer language is and think that your use of Emacs makes you a genius. My people. =) You know, “Everyone” that’s left  outside of the community. =)

>> You have to get a newbie to understand what M-x eww is. “Just RTFM”
>> isn’t the same anymore. Veronica just did a video on how “The Manual”
>> has changed over the years:
>> https://www.youtube.com/watch?v=4lUiUQOvRHQ (this should be required
>> viewing for anyone writing help files today - they even used to
>> explain what the space bar is used for.) My point is: Emacs, while
>> powerful, while understandable by those with a modicum of time and
>> maybe a slight bit of computer experience, is not newbie friendly. I’m
>> not aiming to hold the hands of developers who are used to looking up
>> functions on the fly; I’m proposing we have a page with sub-pages of
>> easily understood material for non-developers and coders. I also am
>> not proposing that we “change” Emacs in any way - I love Emacs the way
>> it is. It’s just want an instantly available newbie section. It’s not
>> a huge ask, right? =)
> 
> I am not disagreeing, I just want to qualify this with my own impression
> that a big problem nowadays is that people just don't want to read, no
> matter what you write.  An indication for this might be that when I
> tried out VSCode a few months ago, and I tried to open up a manual to
> study the program properly, all I could find was a series of videos with
> some light commentary.  And I suspect most people don't even watch them?

This is true. I’m trying to reach them anyway. =)

> -- 
> 	Philip Kaludercic on siskin

Summer Emacs.

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

Re: Emacs Newbie Info Pages

[Juergen Fenn]

Am 13.09.24 um 09:39 Uhr schrieb Summer Emacs:
>
> Well, since I keep hearing “Emacs is for everyone” and “Free software is
> for everyone”, I’m imagining some of my friends: people who use their
> phones and iPads, Tik Tok, iMessage, WhatsApp, and who don’t ever look
> at a computer unless they have to at work or in class. People like me
> who didn’t know how to do much of anything other than open a file, write
> in it, click a few buttons, and send it off in an Email. Those people.
> Regular people. People who don’t know what a function or a variable is.
> People who don’t know what a computer language is and think that your
> use of Emacs makes you a genius. My people. =) You know, “Everyone”
> that’s left  outside of the community. =)

Well, I taught people like your friends for some ten years how to use
computers. This worked out well because I am not a developer myself, but
I also struggle to get going with operating systems and applications.

You can explain to a newbie how to install, start, and work with Emacs.
But what you probably can't do is to convince someone who prefers mobile
apps to desktop systems that it would be better for him to use the
latter. Emacs and other fine pieces of software are not for people that
do not find its advantages to be obvious for all the world to see. When
I discovered Emacs sometime around 2000, it was love at first sight. :)

So, an introduction to Emacs and Emacs Lisp for the 21st century would
not mind to address the vast majority of mobile app users and preach
them to show repentance and to finally join the church of Emacs.

Rather, it would avoid the Emacs-specific vocabulary no one outside our
own bubble understands right away. It would use plain words that anyone
who knows how to use a computer understands anyway. And it would explain
some differences between platforms, such as what is Meta key on the Mac.
This isn't much, but it is probably where most new users fail.

YMMV.

If time permits, I could provide such an introduction for new Emacs
users on the Mac.

Regards,
Jürgen.

Re: Emacs Newbie Info Pages

[Thanos Apollo]

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

Philip Kaludercic <philipk@posteo.net> writes:


[...]

> --8<---------------cut here---------------start------------->8---
> [package avy]
> set all-windows all-frames
> bind C-z avy-goto-word-1
>
> [package auctex]
> set TeX-master dwim
> hook TeX-language-de-hook site/use-german
> rebind RET newline 
>
> [package bash-completion]
> (bash-completion-setup)
> --8<---------------cut here---------------end--------------->8---
>
> where the common patterns are simplified and made safe (e.g. the "set"
> directive wouldn't evaluate) but still remains powerful, as you can
> intersperse lisp code.  If I ever get around to finishing this -- or
> anyone else decides to steal the idea ;) -- then adding this to the core
> and loading ~/.emacs.d/init.conf if it exists might be a useful thing to
> mention in a newbie manual.
>

Using non-lispy language for configuring Emacs wouldn't be appropriate,
as it could make using emacs lisp intimidating.  It would be preferable
to gently guide and support a user in their first steps with setting up
emacs, using emacs lisp, to help them accomplish their tasks
effectively.

A better option might be to adopt a system similar to =doom!= macro that
enables "modules" in Doom Emacs for OOB experience (e.g., Python
development, emails etc).  Additionally, a web page or wiki detailing
recommended packages and their use-package snippets for various
programming languages and tasks that emacs developers use & recommend
would be helpful, even more than a getting started guide.

I should also note that the info pages are really well done & the code
that is written in emacs is well documented for users eager to delve
deeper once they're more confident.  However, reaching that point can be
daunting.


-- 
Thanos Apollo
https://thanosapollo.org

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

Re: Emacs Newbie Info Pages

[Corwin Brust]

On Thu, Sep 12, 2024 at 12:30 PM Summer Emacs <summeremacs@summerstar.me> wrote:
>
> Hi everyone,
>
> I posted a question in Reddit this morning about having an Emacs newbie info pages on the front of the default Emacs page for complete newbies and first-timers. I know that the splash page already has information links, which are very appreciated, but I think that first time users would be overwhelmed with the information and how to use it.

I had a potentially relatable idea the other day, which I will risk
hijacking your (fine) thread to mention (but do feel free to
disregard, if you feel I'm over wrong in thinking it could make sense
to take on what I suggest in context of what you propose).

I have for some time been "thumping the theory" (meaning: occasionally
mentioning in email or on IRC, etc) that we might have taken the wrong
direction, from a long term approach standpoint and not any of the
micro-decisions leading us here, to lump "introductory features"
together with every other change we make to Emacs.  This leads us in
some cases, I think, to conceal such features from exactly the users
whom they have been added to serve.  It's not a trivial problem,
either to understand the nuances of or define a way forward, even if
one were to completely agree with everything I say.

But I might have a suggestion, as of the other day.  I can't recall
seeing it discussed but it's quite possible I missed that; sorry if I
happen to be beating a dead horse.  In any case: seeing your email has
me thinking now is the time to mention.

To put things as simply as I can:
1.  We (quite rightly) hide significant changes from behind guards
such as configuration settings as a general practice.  This minimizes
the noise for regular users of Emacs who would like to stay abreast of
recent development but who do not want to make an endless series of
configuration changes to continue their existing workflows except
where they have introduced desired changes in their configuration.
Well and good.

2.  Meanwhile, we have an increasingly complex set of expectations
which are maintained in terms of the guards, default values for
variables intended for user settings/configuration and functions that
evaluate (have expert knowledge of) these.  I don't suggest it is
unmanageable, only that it might be slightly suboptimal for everyone
involved.

Would it make sense to have a `emacs-welcome-new-user' mode which
"collects" configuration defaults appropriate for new users and
provides means to enable (and, perhaps, disable) them en masse?

I imagine this could be done without major change to existing defaults
and still be quite useful to new users.  For example, a command line
option, easy to reach bindings perhaps under C-h, menu options,
integration with or button on the spash-screen, etc, off the top of my
head, seem like ways to offer this functionality that are unlikely to
represent any meaningful change to long-time Emacs users.

If we did eventually want to change the way we approach defaults, this
might provide a useful experiment in the direction of grouping
features logically.  I leave aside the question of enabling this new
minor mode by default and thus any contribution to a discussion of
whether or not existing users would accept all having to make this
change (given we mostly won't be building 'all this functionality for
new users' for ourselves). I think simply defining the enable and
disable progns or whathaveyou invoked from there seems could provide a
technical direction to explore, which could breaking the cycle of
having to individually (using Anti-NEWS, or whatever) disable each
change we don't happen to like, and free maintainers a little bit from
having to "hide the fun new things".  That said, I have no specific
"feature groups" to suggest other than the "new user friendly
defaults" suggestion, which could be at hand in this thread.

Meanwhile, generally, I do think a collection of features (in this
case "for newer users") can be a very powerful concept.  In chat, we
often need to point to -Q/-q (or explain the difference) to people
getting started who are asking questions on Emacs IRC channels.  This
type of advice, much as reminding people about the existence of the
tutorial or helping someone get started using info (or man) along with
getting friendly with Emacs' fine manual, can be an invaluable part of
some given new user's Emacs starter-kit.  In passing, I think it worth
mentioning that programs like Doom provide as an (IMO) important
feature, a logical grouping of features.   I'm not suggesting creating
something akin to this, expressly, but that would be a direction to
consider that I suspect could give the results I have in mind.

In summary, I think it would be easy enough to point people (who don't
notice in the documentation) how to find a command line option or
keystrokes to start emacs in "new user mode" (perhaps, implemented as
a minor mode?).  By "grouping" evaluation of certain parts of user
context when the minor mode is toggled (or conditioned on whether it
is enabled, some setting it pays attention to to autoenable, etc) we
could create a model for grouping such other functions that "leaves
the code in one place", in that it doesn't require implementing any
logical framework for feature grouping (but could likely be
implemented according to such).


The goal of this project would be the following:
>

Thanks for your note.

Re: Emacs Newbie Info Pages

[Summer Emacs]

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



> On Sep 12, 2024, at 20:29, Corwin Brust <corwin@bru.st> wrote:
> 
> On Thu, Sep 12, 2024 at 12:30 PM Summer Emacs <summeremacs@summerstar.me <mailto:summeremacs@summerstar.me>> wrote:
>> 
>> Hi everyone,
>> 
>> I posted a question in Reddit this morning about having an Emacs newbie info pages on the front of the default Emacs page for complete newbies and first-timers. I know that the splash page already has information links, which are very appreciated, but I think that first time users would be overwhelmed with the information and how to use it.
> 
> I had a potentially relatable idea the other day, which I will risk
> hijacking your (fine) thread to mention (but do feel free to
> disregard, if you feel I'm over wrong in thinking it could make sense
> to take on what I suggest in context of what you propose).

Well I said I welcome all suggestions and constructive criticism and input so I’m not going to say no. =)

> 
> I have for some time been "thumping the theory" (meaning: occasionally
> mentioning in email or on IRC, etc) that we might have taken the wrong
> direction, from a long term approach standpoint and not any of the
> micro-decisions leading us here, to lump "introductory features"
> together with every other change we make to Emacs.  This leads us in
> some cases, I think, to conceal such features from exactly the users
> whom they have been added to serve.  It's not a trivial problem,
> either to understand the nuances of or define a way forward, even if
> one were to completely agree with everything I say.
> 
> But I might have a suggestion, as of the other day.  I can't recall
> seeing it discussed but it's quite possible I missed that; sorry if I
> happen to be beating a dead horse.  In any case: seeing your email has
> me thinking now is the time to mention.
> 
> To put things as simply as I can:
> 1.  We (quite rightly) hide significant changes from behind guards
> such as configuration settings as a general practice.  This minimizes
> the noise for regular users of Emacs who would like to stay abreast of
> recent development but who do not want to make an endless series of
> configuration changes to continue their existing workflows except
> where they have introduced desired changes in their configuration.
> Well and good.

You’re getting into territory I wanted to avoid with this. The reason why is because I want to add something to Emacs without changing Emacs. I know from a few years of conversation now how contentious the idea is of changing anything core to Emacs. All I want to do is at least start simple. A simple info pages with a visible link. It wouldn’t change Emacs in any way other than adding more to a section of info pages and one line at the top of the welcome screen. I think starting small is the way to go, even if there is a lot of info behind that link divided up in different ways.

> 
> 2.  Meanwhile, we have an increasingly complex set of expectations
> which are maintained in terms of the guards, default values for
> variables intended for user settings/configuration and functions that
> evaluate (have expert knowledge of) these.  I don't suggest it is
> unmanageable, only that it might be slightly suboptimal for everyone
> involved.
> 
> Would it make sense to have a `emacs-welcome-new-user' mode which
> "collects" configuration defaults appropriate for new users and
> provides means to enable (and, perhaps, disable) them en masse?
> 
> I imagine this could be done without major change to existing defaults
> and still be quite useful to new users.  For example, a command line
> option, easy to reach bindings perhaps under C-h, menu options,
> integration with or button on the spash-screen, etc, off the top of my
> head, seem like ways to offer this functionality that are unlikely to
> represent any meaningful change to long-time Emacs users.
> 
> If we did eventually want to change the way we approach defaults, this
> might provide a useful experiment in the direction of grouping
> features logically.  I leave aside the question of enabling this new
> minor mode by default and thus any contribution to a discussion of
> whether or not existing users would accept all having to make this
> change (given we mostly won't be building 'all this functionality for
> new users' for ourselves). I think simply defining the enable and
> disable progns or whathaveyou invoked from there seems could provide a
> technical direction to explore, which could breaking the cycle of
> having to individually (using Anti-NEWS, or whatever) disable each
> change we don't happen to like, and free maintainers a little bit from
> having to "hide the fun new things".  That said, I have no specific
> "feature groups" to suggest other than the "new user friendly
> defaults" suggestion, which could be at hand in this thread.
> 
> Meanwhile, generally, I do think a collection of features (in this
> case "for newer users") can be a very powerful concept.  In chat, we
> often need to point to -Q/-q (or explain the difference) to people
> getting started who are asking questions on Emacs IRC channels.  This
> type of advice, much as reminding people about the existence of the
> tutorial or helping someone get started using info (or man) along with
> getting friendly with Emacs' fine manual, can be an invaluable part of
> some given new user's Emacs starter-kit.  In passing, I think it worth
> mentioning that programs like Doom provide as an (IMO) important
> feature, a logical grouping of features.   I'm not suggesting creating
> something akin to this, expressly, but that would be a direction to
> consider that I suspect could give the results I have in mind.
> 
> In summary, I think it would be easy enough to point people (who don't
> notice in the documentation) how to find a command line option or
> keystrokes to start emacs in "new user mode" (perhaps, implemented as
> a minor mode?).  By "grouping" evaluation of certain parts of user
> context when the minor mode is toggled (or conditioned on whether it
> is enabled, some setting it pays attention to to autoenable, etc) we
> could create a model for grouping such other functions that "leaves
> the code in one place", in that it doesn't require implementing any
> logical framework for feature grouping (but could likely be
> implemented according to such).

As above: I wouldn’t even know where to begin with such a thing. I like the idea! But I think it would cause years of infighting perhaps and some people would be dead set against it. I wanted to do it this way because:
1) I could help write things for it along with others and
2) It’s really easy to do and would require almost no coding at all - 99% of the work would be writing and editing, and selecting things for examples.

This would not change Emacs in any way, behind the hood or in front. I think it’s the best approach I can imagine for now without having a war erupt. =)

> 
> 
> The goal of this project would be the following:
>> 
> 
> Thanks for your note.

And thank you for yours! Again: I’m not against it but it’s not what I wanted to start as a discussion as I figure some people would be against adding any sort of special thing to Emacs or pre-set config. My suggestion would include different configs (for non-devs mostly) and different themes/examples as well as hand holding on how to find the commands they need and how to set up their own config eventually. More than that would be pointed to in the existing info pages (which are excellent but a bit daunting for beginners). My plan is to get them up and running enough so that what *is* in the help files isn’t that daunting anymore. =)

Summer Emacs.


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

Re: Emacs Newbie Info Pages

[Suhail Singh]

Corwin Brust <corwin@bru.st> writes:

> Would it make sense to have a `emacs-welcome-new-user' mode which
> "collects" configuration defaults appropriate for new users and
> provides means to enable (and, perhaps, disable) them en masse?

A dedicated "initialization" command (be it `emacs-welcome-new-user' or
`emacs-initialize-configuration' or something else) could be useful.  If
said command is linked to from the initial splash screen, it would also
make it accessible.

I see this as a variation of the current "Customize Startup" option, but
not a substitute for it.  In order to "generate appropriate
configuration defaults" this command would be allowed to ask the user
questions, however, said questions have to be answerable by the user
without them necessarily having read the manual (e.g., questions about
possible usage patterns or tasks a user may want to accomplish with
Emacs).  Contrast this with "Customize startup" which requires the user
to have some awareness of Emacs concepts and doesn't focus on "usage
patterns".

> In passing, I think it worth mentioning that programs like Doom
> provide as an (IMO) important feature, a logical grouping of features.
> I'm not suggesting creating something akin to this, expressly, but
> that would be a direction to consider that I suspect could give the
> results I have in mind.

While I don't have experience with Doom, I agree with the general belief
regd. "logical grouping of features" where "logical" means from the
perspective of the uninitiated user.

-- 
Suhail

Re: Emacs Newbie Info Pages

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

How does this proposed Info manual compare with the C-h t Emacs
tutorial?  If they are doing different jobs, how do they differ?

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

Re: Emacs Newbie Info Pages

[Summer Emacs]

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

> On Sep 17, 2024, at 05:47, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
> How does this proposed Info manual compare with the C-h t Emacs
> tutorial?  If they are doing different jobs, how do they differ?

Good questions! Thank you.

1) My proposal is for new people to have a landing set of pages to click through, explaining things in a clear and easy way for them to understand without the instant introduction of concepts which are alien to them. I think the help files are a great thing, but they are overwhelming for new people. I know this because I’ve shown it to people in my circles who don’t know much of anything about how to use a computer, but still use applications such as Word or Pages to type up things for work/classes. They couldn’t understand the first thing about the help pages.

I think there are a few reasons for this, but the most notable one is that programmers (which seems to comprise the vast majority of Emacs users) tend to take a lot of terms and concepts for granted. This makes the default help files and GNU eww page a bit overwhelming for most people. I want to introduce them to the things they need to get started and comfortable before showing them that vast amount of information.

Also, programmers are people who, when they don’t understand a term (or function or variable) instantly look it up. Most people don’t do that. And if we show them how to do, for instance, C-h v and then type a variable name, the documentation which follows is rarely understandable by people without any sort of coding background. Let’s be real: Most people don’t even know what a function or variable is. It’s not something they use in every day conversation or on their computers. Learning Emacs will teach them this of course, but I don’t want it to be the first thing they start learning.

2) There is an EmacsWiki page for Emacs Newbies, and I have been going over it and other written material provided by other volunteers. I want to consolidate things into easily understood sections. Therefore, I have put up the page I’m working on (it’s a very, very, very unfinished rough rough rough draft) laying out the ideas I have so far. It’s going to change in very big ways, sections will be moved, more will be added. But if anyone wants to contribute/add/edit, please feel free. It’s on GitHub (which I know isn’t people’s favourite around here, but I use it because I don’t really know others and I’m not a coder/developer so please bear with me as I learn):

https://github.com/summeremacs/Emacsnewbie/blob/main/20240912T175822--emacs-welcome-newbie-screen__emacs_help_tutorial.org
If anyone has any corrections/deletions/suggestions/additions, please let me know. I know I’m a regular user but I’m very willing to learn. If I make a mistake, it’s not intentional.

In summary: I think that Emacs COULD be for a lot of people who aren’t using it. I think most people CAN learn. Also, let me reiterate: whomever wrote the navigation/editing tutorial in Emacs hit the nail on the head. It taught me very quickly what I needed to know and it was written for total newbies. It’s something I appreciate a lot and it will be the first tutorial the new user in these pages will learn (there will be a link to point to it and info on how to get back provided).

Thanks again to anyone who provides any help or tips/feedback. I’m taking it all in. I have my regular job I’m really busy with but I’m getting it all done as fast as possible.


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


[-- Attachment #2.1: Type: text/html, Size: 7721 bytes --]

[-- Attachment #2.2: apple-touch-icon-180x180-a80b8e11abe2.png --]
[-- Type: image/png, Size: 21128 bytes --]

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Tue, 17 Sep 2024 12:58:21 +0200
> Cc: Suhail Singh <suhailsingh247@gmail.com>, corwin@bru.st, emacs-devel@gnu.org
> 
> > How does this proposed Info manual compare with the C-h t Emacs
> > tutorial?  If they are doing different jobs, how do they differ?
> 
> Good questions! Thank you.
> 
> 1) My proposal is for new people to have a landing set of pages to click through, explaining things in a clear and easy way for them to understand without the instant introduction of concepts which are alien to them. I think the help files are a great thing, but they are overwhelming for new people. I know this because I’ve shown it to people in my circles who don’t know much of anything about how to use a computer, but still use applications such as Word or Pages to type up things for work/classes. They couldn’t understand the first thing about the help pages.

I think Richard asked about the difference between what you propose
and the existing Emacs tutorial (which can be read by typing "C-h t").
The tutorial is not what you call "help files", and is written in a
different style and with different goals in mind.

Or are you saying that the tutorial is also overwhelming, in
particular due to introducing too many alien concepts?  If so, that
might be worth a separate discussion, because the tutorial is not
supposed to be hard to read and understand.

Re: Emacs Newbie Info Pages

[Summer Emacs]

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

> On Sep 17, 2024, at 15:31, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Summer Emacs <summeremacs@summerstar.me>
>> Date: Tue, 17 Sep 2024 12:58:21 +0200
>> Cc: Suhail Singh <suhailsingh247@gmail.com>, corwin@bru.st, emacs-devel@gnu.org
>> 
>>> How does this proposed Info manual compare with the C-h t Emacs
>>> tutorial?  If they are doing different jobs, how do they differ?
>> 
>> Good questions! Thank you.
>> 
>> 1) My proposal is for new people to have a landing set of pages to click through, explaining things in a clear and easy way for them to understand without the instant introduction of concepts which are alien to them. I think the help files are a great thing, but they are overwhelming for new people. I know this because I’ve shown it to people in my circles who don’t know much of anything about how to use a computer, but still use applications such as Word or Pages to type up things for work/classes. They couldn’t understand the first thing about the help pages.
> 
> I think Richard asked about the difference between what you propose
> and the existing Emacs tutorial (which can be read by typing "C-h t").
> The tutorial is not what you call "help files", and is written in a
> different style and with different goals in mind.
> 
> Or are you saying that the tutorial is also overwhelming, in
> particular due to introducing too many alien concepts?  If so, that
> might be worth a separate discussion, because the tutorial is not
> supposed to be hard to read and understand.
> 

I did mention the tutorial but I said I think it’s fantastic. I was speaking about the other help files in general. Such as clicking on the “Emacs guided tour” - it’s very non-newbie friendly. It’s a great resource but I think we need something better for brand new users who don’t have a coding background.

The first lines in the manual are:
The GNU Emacs Manual calls Emacs the extensible, customizable, self-documenting real-time
display editor, but this description tells beginners little about what Emacs is capable of.
To give you an idea, here is a sampling of the things you can do with Emacs:

Beyond just being able to edit plain text files, Emacs includes special features to help
you write in many different human languages and programming/markup languages:

Now, that’s not too bad (except most people have no idea what extensible means). The second sentence talks about programming/markup languages: most people will think it’s just for programmers. You don’t open up another text editor and it starts talking about programming in the second line. This is not a problem if the person is good with computers and knows a little bit of programming, but that doesn’t describe most people.

The third line is the following:

…as well as tools for compiling, running, and testing programs. Emacs integrates with
GDB to provide an IDE (M-x gdb):

This is completely gobbledygook to most people. My survey results with non-devs:
(Compiling?)
(Running?)
(GDB - fergetabboudit)
(IDE - what?)
(M-x gdb) what’s an M-x?

Again: Great for programmers - they’ll get it, even if they’re completely new to Emacs. They’ll figure it out. Non-programmers? Not so much.

Fourth line:

Emacs can compare two files and highlight their differences (M-x ediff):

Interesting. Most people don’t worry about that as much, however (even if it’s super useful even in non-programming uses). But at the start? Confusing.

Next line:

Emacs is a file manager (M-x dired):

Most people, who actually use file managers, don’t know what a file manager is. I’m a huge, huge, advocate for dired and think that it’s the best thing since sliced bread. In fact, I use it hundreds of times a day now. But throwing that in my face from the start only really confused me about it.

Emacs can read news, mail, and RSS feeds (M-x gnus):

Awesome! That’s interesting, though most people don’t know what RSS is and still don’t know what M-x is. But telling them some basics of what it can do is good.

You can even play tetris in Emacs (M-x tetris):

Good again. But let’s not throw games at them while they’re brand new and still don’t know what commands are. We can put stuff like that towards the end of the tutorial.

You might see now why some people consider Emacs to be not merely a text editor but
almost a complete operating system. Some users find that they can do almost all of their
work from within Emacs.

Good. Most people don’t really know what an operating system is, but it’s not that scary a word/concept to start with. Most people have at least heard of what an operating system is so it’s not going to make them uncomfortable.

These approaches, and more, are going to be addressed in my new tutorial which I posted that I’m working on. I hope that clarifies it a bit? 🙃

Summer Emacs ☀️🐃 

P.S. I should reiterate that my idea is *not* to take away the info pages above in any way, or change them, but just to add one for complete newbies. I don’t want to change Emacs in any way other than add to it with just a section for complete beginners. Nothing, and I mean nothing, is going to be changed by me in any of the tutorials or info pages. All I’m doing is creating a new section for people who don’t have a clue and could be Emacs users with a little help.

P.P.S. If you want an idea of the kind of breakdown and tone I’m trying out, check out the page I’m working on now.


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

Re: Emacs Newbie Info Pages

[Emanuel Berg]

Summer Emacs wrote:

> I did mention the tutorial but I said I think it's

Are we talking about an Emacs tutorial in general or one for
one of its parts?

I read the one for eieio, good - but too few, and not wide
enough, examples. 1 situation - 1 example is ideal for me,
here it was much less and some things I still don't know.

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

Re: Emacs Newbie Info Pages

[Summer Emacs]

> On Sep 17, 2024, at 16:48, Emanuel Berg <incal@dataswamp.org> wrote:
> 
> Summer Emacs wrote:
> 
>> I did mention the tutorial but I said I think it's
> 
> Are we talking about an Emacs tutorial in general or one for
> one of its parts?

In general. It’ll be a whole new section with a link to the emacs tutorial on how to move/edit with the key binds, and more info on how to get back to the newbie pages. If you read what I wrote so far, you’ll get an idea. 🙃

Summer Emacs ☀️🐃 

Re: Emacs Newbie Info Pages

[Emanuel Berg]

Summer Emacs wrote:

> In general. It'll be a whole new section with a link to the
> emacs tutorial on how to move/edit with the key binds, and
> more info on how to get back to the newbie pages.

Well, not all beginners are unimpressive.

I think one shouldn't focus on that, what does it matter?
Better to write interesting and useful things and then anyone,
beginner/veteran, sane/crazy, can read it if they like to and
for whatever reason.

> If you read what I wrote so far, you'll get an idea.

Okay, if you will read what I wrote so far as well then.

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

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Tue, 17 Sep 2024 16:12:17 +0200
> Cc: rms@gnu.org,
>  suhailsingh247@gmail.com,
>  corwin@bru.st,
>  emacs-devel@gnu.org
> 
>  1) My proposal is for new people to have a landing set of pages to click through, explaining things
>  in a clear and easy way for them to understand without the instant introduction of concepts which
>  are alien to them. I think the help files are a great thing, but they are overwhelming for new
>  people. I know this because I’ve shown it to people in my circles who don’t know much of anything
>  about how to use a computer, but still use applications such as Word or Pages to type up things
>  for work/classes. They couldn’t understand the first thing about the help pages.
> 
>  I think Richard asked about the difference between what you propose
>  and the existing Emacs tutorial (which can be read by typing "C-h t").
>  The tutorial is not what you call "help files", and is written in a
>  different style and with different goals in mind.
> 
>  Or are you saying that the tutorial is also overwhelming, in
>  particular due to introducing too many alien concepts?  If so, that
>  might be worth a separate discussion, because the tutorial is not
>  supposed to be hard to read and understand.
> 
> I did mention the tutorial but I said I think it’s fantastic. I was speaking about the other help files in general.
> Such as clicking on the “Emacs guided tour” - it’s very non-newbie friendly. It’s a great resource but I think we
> need something better for brand new users who don’t have a coding background.

OK, but then Richard's question still stands, and it would be good to
hear your view on the difference between what you propose and the
tutorial.  Because I could think about a few follow-up questions, such
as:

  . can we extend the tutorial with the information you would like to
    have in the document you propose?
  . maybe make what you propose to be "tutorial, part2"?
  . or how about a tutorial whose audience is non-programmers?

etc.

Re: Emacs Newbie Info Pages

[Summer Emacs]

> On Sep 17, 2024, at 17:44, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Summer Emacs <summeremacs@summerstar.me>
>> Date: Tue, 17 Sep 2024 16:12:17 +0200
>> Cc: rms@gnu.org,
>> suhailsingh247@gmail.com,
>> corwin@bru.st,
>> emacs-devel@gnu.org
>> 
>> 1) My proposal is for new people to have a landing set of pages to click through, explaining things
>> in a clear and easy way for them to understand without the instant introduction of concepts which
>> are alien to them. I think the help files are a great thing, but they are overwhelming for new
>> people. I know this because I’ve shown it to people in my circles who don’t know much of anything
>> about how to use a computer, but still use applications such as Word or Pages to type up things
>> for work/classes. They couldn’t understand the first thing about the help pages.
>> 
>> I think Richard asked about the difference between what you propose
>> and the existing Emacs tutorial (which can be read by typing "C-h t").
>> The tutorial is not what you call "help files", and is written in a
>> different style and with different goals in mind.
>> 
>> Or are you saying that the tutorial is also overwhelming, in
>> particular due to introducing too many alien concepts?  If so, that
>> might be worth a separate discussion, because the tutorial is not
>> supposed to be hard to read and understand.
>> 
>> I did mention the tutorial but I said I think it’s fantastic. I was speaking about the other help files in general.
>> Such as clicking on the “Emacs guided tour” - it’s very non-newbie friendly. It’s a great resource but I think we
>> need something better for brand new users who don’t have a coding background.
> 
> OK, but then Richard's question still stands, and it would be good to
> hear your view on the difference between what you propose and the
> tutorial.  Because I could think about a few follow-up questions, such
> as:
> 
>  . can we extend the tutorial with the information you would like to
>    have in the document you propose?
>  . maybe make what you propose to be "tutorial, part2"?
>  . or how about a tutorial whose audience is non-programmers?
> 
> etc.

You kinda have to read what I’ve written so far. 😀
The audience is literally for non-programmers. 🙃

Summer Emacs ☀️🐃 

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Tue, 17 Sep 2024 18:49:19 +0200
> Cc: rms@gnu.org,
>  suhailsingh247@gmail.com,
>  corwin@bru.st,
>  emacs-devel@gnu.org
> 
> > OK, but then Richard's question still stands, and it would be good to
> > hear your view on the difference between what you propose and the
> > tutorial.  Because I could think about a few follow-up questions, such
> > as:
> > 
> >  . can we extend the tutorial with the information you would like to
> >    have in the document you propose?
> >  . maybe make what you propose to be "tutorial, part2"?
> >  . or how about a tutorial whose audience is non-programmers?
> > 
> > etc.
> 
> You kinda have to read what I’ve written so far. 😀

I have.  It is still hard for me to know where are you heading, since
what you have there basically just mentions in general all kinds of
capabilities and features you consider important.  It doesn't teach
the reader anything, at least not yet.  So I guess I'll have to wait
till you get more "meat" there.

Thanks.

Re: Emacs Newbie Info Pages

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

  > 1) My proposal is for new people to have a landing set of pages to
  > click through, explaining things in a clear and easy way for them to
  > understand without the instant introduction of concepts which are
  > alien to them. I think the help files are a great thing, but they are
  > overwhelming for new people.

Could you please state concretely what pages you call "Help pages"?  I
don't think we use that term, and I am not sure what you're referring
to.  If you state some precise file names or URLs, then it will be
clear what you mean.

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

Re: Emacs Newbie Info Pages

[Summer Emacs]

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

> On Sep 19, 2024, at 05:51, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>> 1) My proposal is for new people to have a landing set of pages to
>> click through, explaining things in a clear and easy way for them to
>> understand without the instant introduction of concepts which are
>> alien to them. I think the help files are a great thing, but they are
>> overwhelming for new people.
> 
> Could you please state concretely what pages you call "Help pages"?  I
> don't think we use that term, and I am not sure what you're referring
> to.  If you state some precise file names or URLs, then it will be
> clear what you mean.

Sure! I’m talking about the About Emacs page you first see when you boot up Emacs the first time. (C-h C-a). I will detail more thoughts about it in another email in the thread.

Summer Emacs ☀️🐃 
summeremacs@summerstar.me
“Shake it Off <https://www.youtube.com/watch?v=M_JiMkVx0FU>” - Taylor Swift 💖



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

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Corwin Brust <corwin@bru.st>
> Date: Thu, 12 Sep 2024 13:29:40 -0500
> Cc: emacs-devel@gnu.org
> 
> Would it make sense to have a `emacs-welcome-new-user' mode which
> "collects" configuration defaults appropriate for new users and
> provides means to enable (and, perhaps, disable) them en masse?

This was discussed in the past (search the archives), but never went
anywhere beyond the discussion.  The idea is certainly sensible, but
implementing it is a challenge, since different groups of users/usage
patterns need different stuff in such a mode.

Re: Emacs Newbie Info Pages

[Summer Emacs]

> On Sep 13, 2024, at 08:38, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Corwin Brust <corwin@bru.st>
>> Date: Thu, 12 Sep 2024 13:29:40 -0500
>> Cc: emacs-devel@gnu.org
>> 
>> Would it make sense to have a `emacs-welcome-new-user' mode which
>> "collects" configuration defaults appropriate for new users and
>> provides means to enable (and, perhaps, disable) them en masse?
> 
> This was discussed in the past (search the archives), but never went
> anywhere beyond the discussion.  The idea is certainly sensible, but
> implementing it is a challenge, since different groups of users/usage
> patterns need different stuff in such a mode.

Yeah. I’ve been told. The problem with this is the following:

Premise: Everyone is different. Everyone has different needs.

Deduction: No tutorial will ever meet the needs of every single person.

Conclusion: Let’s not do anything.

Instead, let’s try this:

Premise: Most people who use Emacs are devs.
Given: Not everyone who uses Emacs is a dev.
Deduction: The people who aren’t devs may get lost in the assumptions made in Emacs welcome pages.
Conclusion: Let’s make a tutorial for people who aren’t devs.

I think mine sounds better and, maybe with a little luck and a touch of effort, we may get somewhere. =)

Summer Emacs

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Fri, 13 Sep 2024 09:45:25 +0200
> Cc: Corwin Brust <corwin@bru.st>,
>  emacs-devel@gnu.org
> 
> > On Sep 13, 2024, at 08:38, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> From: Corwin Brust <corwin@bru.st>
> >> Date: Thu, 12 Sep 2024 13:29:40 -0500
> >> Cc: emacs-devel@gnu.org
> >> 
> >> Would it make sense to have a `emacs-welcome-new-user' mode which
> >> "collects" configuration defaults appropriate for new users and
> >> provides means to enable (and, perhaps, disable) them en masse?
> > 
> > This was discussed in the past (search the archives), but never went
> > anywhere beyond the discussion.  The idea is certainly sensible, but
> > implementing it is a challenge, since different groups of users/usage
> > patterns need different stuff in such a mode.
> 
> Yeah. I’ve been told. The problem with this is the following:
> 
> Premise: Everyone is different. Everyone has different needs.
> 
> Deduction: No tutorial will ever meet the needs of every single person.
> 
> Conclusion: Let’s not do anything.
> 
> Instead, let’s try this:
> 
> Premise: Most people who use Emacs are devs.
> Given: Not everyone who uses Emacs is a dev.
> Deduction: The people who aren’t devs may get lost in the assumptions made in Emacs welcome pages.
> Conclusion: Let’s make a tutorial for people who aren’t devs.
> 
> I think mine sounds better and, maybe with a little luck and a touch of effort, we may get somewhere. =)

I think the "conclusion" you cite above, to do nothing, is not a
conclusion we arrived at.  (I also think it's a bit unfair to claim
that we arrived at such a "conclusion": it almost says we make silly
conclusions here.)  I think instead we acknowledged the problem and
tried to find solutions for it, like trying to identify the meaningful
classes/groups of users, so as to have a dedicated tutorial/mode for
each one of them.

I think a tutorial for people who are not software developers is an
okay solution, but that doesn't make the issue go away: non-developers
are still not a homogeneous group, and the challenge I mentions still
exists, albeit is perhaps smaller.

Re: Emacs Newbie Info Pages

[Summer Emacs]

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


> On Sep 13, 2024, at 12:46, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Summer Emacs <summeremacs@summerstar.me <mailto:summeremacs@summerstar.me>>
>> Date: Fri, 13 Sep 2024 09:45:25 +0200
>> Cc: Corwin Brust <corwin@bru.st <mailto:corwin@bru.st>>,
>> emacs-devel@gnu.org <mailto:emacs-devel@gnu.org>
>> 
>> Yeah. I’ve been told. The problem with this is the following:
>> 
>> Premise: Everyone is different. Everyone has different needs.
>> 
>> Deduction: No tutorial will ever meet the needs of every single person.
>> 
>> Conclusion: Let’s not do anything.
>> 
>> Instead, let’s try this:
>> 
>> Premise: Most people who use Emacs are devs.
>> Given: Not everyone who uses Emacs is a dev.
>> Deduction: The people who aren’t devs may get lost in the assumptions made in Emacs welcome pages.
>> Conclusion: Let’s make a tutorial for people who aren’t devs.
>> 
>> I think mine sounds better and, maybe with a little luck and a touch of effort, we may get somewhere. =)
> 
> I think the "conclusion" you cite above, to do nothing, is not a
> conclusion we arrived at.  (I also think it's a bit unfair to claim
> that we arrived at such a "conclusion": it almost says we make silly
> conclusions here.)  I think instead we acknowledged the problem and
> tried to find solutions for it, like trying to identify the meaningful
> classes/groups of users, so as to have a dedicated tutorial/mode for
> each one of them.
> 
> I think a tutorial for people who are not software developers is an
> okay solution, but that doesn't make the issue go away: non-developers
> are still not a homogeneous group, and the challenge I mentions still
> exists, albeit is perhaps smaller.

Understood!
Ok. I agree with you entirely though, but I think it would be a really simple affair to start something rather easy to understand for anyone.

Let me give you an example of what I think is a GOOD thing which teaches about Emacs: The Emacs Movement/Keys Tutorial. I think that’s a great tutorial. I understood it. It was easy to follow, and easy to use, and I learned it in no time. Whomever wrote that was great at that job. I want to emulate that for other stuff: Start from the point of view that the user doesn’t know the first thing about anything, and take them through some of the following:
1) What Emacs is and how they will learn it step by step.
2) Configuration
3) Themes (emphasise that they can make it look like they want to but here are a few examples of themes you can try out right now and where to get more and try those out)
4) Packages (We will want to list the major ones for writing/note taking. Org-Mode, EWS, Denote, Org-Roam, Fontaine because fonts are important to people, and Olivetti are some of the ones I’m thinking about.)
There will be more packages listed, and please read what I wrote in my rough draft to cover the fact that we are not favouring certain packages over others:

Emacs has so many packages available from so many people that they can't really all be counted. But rest assured: it numbers in the thousands. Since the assumption for those reading this tutorial is that they are not coders or developers, we are going to focus mostly on packages which will help you get up and running with your writing needs. Here are some suggested packages. There are many more which are not covered here and this is not necessarily an endorsement of one package over another. These are just helpful starting places for new users.

I know that this will be contentious, just like our choosing certain themes and some minimalist configs, but look: we have to start someplace. And we have to make editorial decisions.

What do you think? Also, if anyone else wants to collaborate on the document, I’m absolutely willing to do that and I’m even hoping for it. Please let me know how to go about sharing this with others who are interested in doing this. Do we set up a private email list? Do we collaborate on a git somewhere? I’m not sure how it all works and I’m willing to learn. But I do want to get this done sometime. =)

Before I forget: I include the link to the Emacs Movement/Keys tutorial at the top of my rough draft. People may miss it on the front page and I don’t want them to miss it. Yes, maybe it’s redundant, but if they’re going to click on a “New User? Click here!” thing, I will still want them to see it and do it. Again: I want to use what’s already built into Emacs, not change anything, and just give a landing place for newbies to learn about it.

Summer Emacs.


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

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Fri, 13 Sep 2024 13:20:33 +0200
> Cc: Corwin Brust <corwin@bru.st>,
>  emacs-devel@gnu.org
> 
> Let me give you an example of what I think is a GOOD thing which teaches about Emacs: The Emacs
> Movement/Keys Tutorial. I think that’s a great tutorial. I understood it. It was easy to follow, and easy to use,
> and I learned it in no time. Whomever wrote that was great at that job. I want to emulate that for other stuff:
> Start from the point of view that the user doesn’t know the first thing about anything, and take them through
> some of the following:
> 1) What Emacs is and how they will learn it step by step.
> 2) Configuration
> 3) Themes (emphasise that they can make it look like they want to but here are a few examples of themes you
> can try out right now and where to get more and try those out)
> 4) Packages (We will want to list the major ones for writing/note taking. Org-Mode, EWS, Denote, Org-Roam,
> Fontaine because fonts are important to people, and Olivetti are some of the ones I’m thinking about.)
> There will be more packages listed, and please read what I wrote in my rough draft to cover the fact that we
> are not favouring certain packages over others:
> 
>  Emacs has so many packages available from so many people that they can't really all be counted. But
>  rest assured: it numbers in the thousands. Since the assumption for those reading this tutorial is that
>  they are not coders or developers, we are going to focus mostly on packages which will help you get up
>  and running with your writing needs. Here are some suggested packages. There are many more which
>  are not covered here and this is not necessarily an endorsement of one package over another. These
>  are just helpful starting places for new users.
> 
> I know that this will be contentious, just like our choosing certain themes and some minimalist configs, but
> look: we have to start someplace. And we have to make editorial decisions.
> 
> What do you think?

I think you should write the document and post it, and we can then
take it from there.  This would be a good progress, IMO.

> Also, if anyone else wants to collaborate on the document, I’m absolutely willing to do that
> and I’m even hoping for it. Please let me know how to go about sharing this with others who are interested in
> doing this. Do we set up a private email list? Do we collaborate on a git somewhere? I’m not sure how it all
> works and I’m willing to learn. But I do want to get this done sometime. =)

It's basically up to you, I think.  If you want to set up a repository
(preferably not GitHub, but if you must, that could also do), that's
okay as a starting point.  We can leave the decision of how to proceed
to later.

Re: Emacs Newbie Info Pages

[Summer Emacs]

> On Sep 13, 2024, at 13:57, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Summer Emacs <summeremacs@summerstar.me>
>> Date: Fri, 13 Sep 2024 13:20:33 +0200
>> Cc: Corwin Brust <corwin@bru.st>,
>> emacs-devel@gnu.org
>> 

<SNIP>

>> 
>> What do you think?
> 
> I think you should write the document and post it, and we can then
> take it from there.  This would be a good progress, IMO.

I can but it’s already something like 3 pages. And it’s just a framework.

> 
>> Also, if anyone else wants to collaborate on the document, I’m absolutely willing to do that
>> and I’m even hoping for it. Please let me know how to go about sharing this with others who are interested in
>> doing this. Do we set up a private email list? Do we collaborate on a git somewhere? I’m not sure how it all
>> works and I’m willing to learn. But I do want to get this done sometime. =)
> 
> It's basically up to you, I think.  If you want to set up a repository
> (preferably not GitHub, but if you must, that could also do), that's
> okay as a starting point.  We can leave the decision of how to proceed
> to later.

Ok. I can set up a git on GitHub later this evening or tomorrow and can post the info here I guess. I’ve never used GitHub like that - I just use it to store info for me. I’ll ask on IRC about the specifics on how to proceed before I post the info so I don’t get anything wrong.

Summer Emacs.

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Fri, 13 Sep 2024 14:09:14 +0200
> Cc: Corwin Brust <corwin@bru.st>,
>  emacs-devel@gnu.org
> 
> > I think you should write the document and post it, and we can then
> > take it from there.  This would be a good progress, IMO.
> 
> I can but it’s already something like 3 pages. And it’s just a framework.

One of the challenges is indeed how NOT to make this too long, or more
accurately: how to prevent the readers from stopping reading too
early.  It's not a simple problem to solve, given the amount of
"important features" to cover.

Re: Emacs Newbie Info Pages

[Emanuel Berg]

Summer Emacs wrote:

> Deduction: No tutorial will ever meet the needs of every
> single person.

We should forget about them, people don't read them anyway.

We must make Emacs super-intuitive, completely smooth,
predicatable for everyone, always.

One will never achieve that goal but if one thinks of that
whatever you do or add, smallest detail, yeah - how far can
we come?

The smartphone revolution and generation has showed that dogma
is nothing. Take the desktop model, throw away the model, all
80s office style pushing papers (files), and just focus on
what the actual application should do - see what happens.

Read my lips, kids whose age consist of a single digit are
using software that is sometimes more advanced that what we
offer and they didn't read a single word about it, some of
them cannot even read!

I'm not saying we should do a smartphone out of Emacs, but we
should start thinking like that. Add documentation if you
like, but if it is needed, think even harder on making it
intuitive, cut all corners, speed is your friend as a user
that can basically move thru the whole place pretty fast also
gets a spacial awareness.

Not "keep it simple", MAKE it simple. We see this trend
everywhere, modern MTBs for example which are 20 times as
advanced yet 100 times easier to pick apart and back together
than muscling with them heavy wrenches as in the golden days.

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

Re: Emacs Newbie Info Pages

[Juergen Fenn]

Am 18.09.24 um 10:13 Uhr schrieb Emanuel Berg:
>> Deduction: No tutorial will ever meet the needs of every
>> single person.
> We should forget about them, people don't read them anyway.
>
> We must make Emacs super-intuitive, completely smooth,
> predicatable for everyone, always.
>
> One will never achieve that goal but if one thinks of that
> whatever you do or add, smallest detail, yeah - how far can
> we come?

I think that's a really good point.

But I wonder whether we might still include a tutorial that draws on a
trend that received much attention in the blogs and in the forums
recently, viz. the idea of "Emacs for writing prose". Summer Emacs also
mentioned "Emacs Writing Studio" which is an example for that. Maybe a
section in the tutorial for those using Emacs not for writing code, but
for writing prose would be a good idea?

@Summer Emacs: In case you feel misunderstood, you might still begin
writing a tutorial of your own and propose it for inclusion into the
Emacs Manual. It is probably better to discuss a concrete text.

Best regards,
Jürgen.

Re: Emacs Newbie Info Pages

[Emanuel Berg]

Juergen Fenn wrote:

> Maybe a section in the tutorial for those using Emacs not
> for writing code, but for writing prose would be
> a good idea?

Yes, absolutely, if someone is willing and able to do that in
a good way.

But even better IMO would be to find out what runs
counter-intuitive to the majority of those people, what it is
they struggle with. So we can fix that. And this is actually
the same for programmers.

So we treat the majority good by handing them Emacs as they
expect it.

And we treat the minority good by still offering the
configuration/extension possibility.

Because then we have the majority _and_ the minority!

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

Re: Emacs Newbie Info Pages

[Eli Zaretskii]

> From: Summer Emacs <summeremacs@summerstar.me>
> Date: Thu, 12 Sep 2024 19:30:57 +0200
> 
> Hi everyone,

Thank you for your interest in Emacs.

First, about terminology: please don't use the phrase "Info pages".
Unlike man pages, an Info manual is not a collection of
loosely-coupled pages, it is a coherent book with sensible structure
of chapters, sections, and subsections, and with menus and
cross-references between them as appropriate.

> I posted a question in Reddit this morning about having an Emacs newbie info pages on the front of the default Emacs page for complete newbies and first-timers. I know that the splash page already has information links, which are very appreciated, but I think that first time users would be overwhelmed with the information and how to use it. The goal of this project would be the following:
> 
> 1) A very visible (easy to see, and hard to miss) link at the top which says something like “New to Emacs? Click here!”
> 2) A simple “one page” info page with some general information about Emacs and suggested setups. This would include:
> 
> a) The link to the Emacs movement/editing tutorial (vital) and why it is necessary to go through it.
> b) A quick overview for non-coders/devs on how Emacs is special and can be made to look like anything they want it to look like.
> c) An explanation of how to configure Emacs in a basic way with a few links to some suggested configs to get started “out of the box” (I know this is contentious, please don’t bite my head off)
> d) How they can download themes right away with some examples of some basic themes and links to some popular theme packages.
> e) An explanation of some bigger packages which they might be interested in as non-coders (mostly writers or other office jobs) such as: Org-Mode, EWS, Denote, Org-Roam, Fontaine, etc…a quick explanation of what each one does, a link to the page where the information can be found.
> f) How to use the configuration panels if they choose to go that route with a few quick examples for them to try out.

I think something like this will be most useful, if done right.  The
challenge, as always, is to do it right.  And the most challenging
aspect of the above job is to select what to describe and what not to
describe, since Emacs is so large, and since each class of users has
different parts of Emacs that are important enough to be in that
"newbie stuff".

The next challenge is how to have this "newbie stuff" in the face of a
newbie, without annoying newbies and veteran users alike.

> Now, a few things:
> 1) I’m not a dev. This is just my take from a non-dev perspective.
> 2) I’ve heard there was work on a wizard setup a while back but that it never went anywhere. My suggestion is to use the info pages instead of a wizard, but to make a newbie “home base” for new users which won’t overwhelm them. I’ve already written about 3 pages but it is very rough and needs a lot of work, links put in, and a lot of editing because my tone is very different from the tone of the manuals. I’ve never written a tutorial before, so I’m going to need some volunteers to help me with some of this stuff.
> 3) I don’t know what it takes to include such a thing into Emacs proper. I don’t know how to patch things, or know what the specifics are for submitting things in a proper way. Please don’t hold that against me - I’m willing to learn.
> 
> I wanted to write this email to put something concrete down rather than just say “Emacs needs to be better for newbs” and not do anything about it. Somebody suggest that I actually do, so I’m going to try.

If we are talking about an Info manual or a tutorial, then just
writing the text to be included there would go a long way towards the
goal.  Someone else can then add markup and install the result in the
Emacs sources, but that is mostly a technical job that has few if any
challenges.

So if you want to propose a text to the above effect, please do, and
TIA.