From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Summer Emacs Newsgroups: gmane.emacs.devel Subject: Re: Emacs Newbie Info Pages Date: Thu, 12 Sep 2024 21:00:41 +0200 Message-ID: References: Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3776.700.51\)) Content-Type: multipart/alternative; boundary="Apple-Mail=_0B97CF6B-7D57-47FD-AC20-32428F2A3FA5" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16630"; mail-complaints-to="usenet@ciao.gmane.io" To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Sep 12 21:01:46 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1sop4b-00048U-9b for ged-emacs-devel@m.gmane-mx.org; Thu, 12 Sep 2024 21:01:45 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sop3y-0005jG-9r; Thu, 12 Sep 2024 15:01:06 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sop3x-0005j7-01 for emacs-devel@gnu.org; Thu, 12 Sep 2024 15:01:05 -0400 Original-Received: from st43p00im-zteg10073501.me.com ([17.58.63.180]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sop3t-0004d0-4v for emacs-devel@gnu.org; Thu, 12 Sep 2024 15:01:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=summerstar.me; s=sig1; t=1726167659; bh=S6oV9/EkTWV+EBe8k6RnfNNQv/XF0vYrCmgkSac+XOs=; h=From:Content-Type:Mime-Version:Subject:Date:To:Message-Id; b=mRHKVSPkMuQ6y025GUG7gYa7PcJr3Ox0EAR5d1xnFq5HxbRPRjyxKA6oC7T2PbEtn gdlVEYpYTA/TTDoTva+xUlaVe5OIq/WtHaLMlVLfPqmk/v2ynRbygt3/mZKo42hjOz 32DL+xtrjx0tOm8EpBrRI6lwBMeNfCKzFU4aqSBN5+Zmak8lOl9qoHus43Jlusu3T3 yeQ4yPlNiOJSmK4ab/lM8tXgBOdc4ulrGCDcpx/UvqjGmVsq7Hb98WT1nixX2BgI0+ hQEhn7EIZP54A0VV0TrZe46fvXQbFAeitPlRdKG+xX/oSIZS/1eksk4CjYR84qYFGv uS0cqBriuMf+A== Original-Received: from smtpclient.apple (st43p00im-dlb-asmtp-mailmevip.me.com [17.42.251.41]) by st43p00im-zteg10073501.me.com (Postfix) with ESMTPSA id 26102A00481 for ; Thu, 12 Sep 2024 19:00:55 +0000 (UTC) In-Reply-To: X-Mailer: Apple Mail (2.3776.700.51) X-Proofpoint-ORIG-GUID: 4qBNjqg-gN1IyD-695e96FbDxWsCZnp5 X-Proofpoint-GUID: 4qBNjqg-gN1IyD-695e96FbDxWsCZnp5 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.272,Aquarius:18.0.1039,Hydra:6.0.680,FMLib:17.12.60.29 definitions=2024-09-12_07,2024-09-12_01,2024-09-02_01 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 bulkscore=0 mlxscore=0 phishscore=0 suspectscore=0 malwarescore=0 adultscore=0 clxscore=1030 mlxlogscore=999 spamscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2308100000 definitions=main-2409120141 Received-SPF: pass client-ip=17.58.63.180; envelope-from=summeremacs@summerstar.me; helo=st43p00im-zteg10073501.me.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:323566 Archived-At: --Apple-Mail=_0B97CF6B-7D57-47FD-AC20-32428F2A3FA5 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On Sep 12, 2024, at 20:29, Corwin Brust wrote: >=20 > On Thu, Sep 12, 2024 at 12:30=E2=80=AFPM Summer Emacs = > wrote: >>=20 >> Hi everyone, >>=20 >> 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. >=20 > 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=E2=80=99m not going to say no. =3D) >=20 > 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. >=20 > 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. >=20 > 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=E2=80=99re 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=E2=80=99t= 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. >=20 > 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. >=20 > 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? >=20 > 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. >=20 > 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. >=20 > 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. >=20 > 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=E2=80=99t 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=E2=80=99s 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=E2=80=99s the best approach I can imagine for now without = having a war erupt. =3D) >=20 >=20 > The goal of this project would be the following: >>=20 >=20 > Thanks for your note. And thank you for yours! Again: I=E2=80=99m not against it but it=E2=80=99= 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=E2=80=99t that daunting anymore. =3D) Summer Emacs. --Apple-Mail=_0B97CF6B-7D57-47FD-AC20-32428F2A3FA5 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8

On Sep 12, 2024, at 20:29, Corwin Brust = <corwin@bru.st> wrote:

On Thu, Sep 12, 2024 at = 12:30=E2=80=AFPM 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).

Well I said I welcome all = suggestions and constructive criticism and input so I=E2=80=99m not = going to say no. =3D)


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=E2=80=99= 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=E2=80=99t = 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=E2=80=99t= 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=E2=80=99s 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=E2=80=99s the best approach = I can imagine for now without having a war erupt. = =3D)



The = goal of this project would be the following:


Thanks = for your note.

And thank you for = yours! Again: I=E2=80=99m not against it but it=E2=80=99s 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=E2=80=99t = that daunting anymore. =3D)

Summer = Emacs.

= --Apple-Mail=_0B97CF6B-7D57-47FD-AC20-32428F2A3FA5--