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 20:45:48 +0200 Message-ID: <391666A2-D4BA-4DFE-9FF6-CAA48797EC97@summerstar.me> References: <87wmjg4tkq.fsf@posteo.net> Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3776.700.51\)) Content-Type: multipart/alternative; boundary="Apple-Mail=_75604091-64C1-4B40-BC87-CEEE6C7A9EDC" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38341"; 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 20:46:56 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 1sooqF-0009mu-3h for ged-emacs-devel@m.gmane-mx.org; Thu, 12 Sep 2024 20:46:55 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1soopY-00037X-OJ; Thu, 12 Sep 2024 14:46:12 -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 1soopX-00037I-BS for emacs-devel@gnu.org; Thu, 12 Sep 2024 14:46:11 -0400 Original-Received: from st43p00im-ztbu10073601.me.com ([17.58.63.184]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1soopS-00039M-Ue for emacs-devel@gnu.org; Thu, 12 Sep 2024 14:46:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=summerstar.me; s=sig1; t=1726166765; bh=XolsVabuOrshaNomnN6n3skK/NiFi2p242n/F266xF0=; h=From:Content-Type:Mime-Version:Subject:Date:To:Message-Id; b=gEjKJvNP8P91wXQIQf569/tE1gMa36lsNJZoACVc/V749K641tTwX6ghxiBJIEx29 /R9I/O2/JzHVAhNGA8doEvW31kxE/D3Z3eNrHiWoKHaYlfv7B5mLIVwNwRYHo0jRRk WToBWMn7vfEV2TPMSa/QxdOABLCYn6IS8UJGwSrf8NdvyyI/6b234rd1fTWZezSTZO k5YoTTlfW9TkZ1s879vTxfh2yj8MgYJTpiP8bA5gMDFdZcVimxFrn6t3zTmaMuhSVF 828ZbjMf0ub0RnxN8k3Rekp97fqmRaArLFa4JIbbUl72gUlb04W1gArQRFsqtMKINK +vc+TkCt53M9A== Original-Received: from smtpclient.apple (st43p00im-dlb-asmtp-mailmevip.me.com [17.42.251.41]) by st43p00im-ztbu10073601.me.com (Postfix) with ESMTPSA id 7C9D21801EE for ; Thu, 12 Sep 2024 18:46:01 +0000 (UTC) In-Reply-To: <87wmjg4tkq.fsf@posteo.net> X-Mailer: Apple Mail (2.3776.700.51) X-Proofpoint-ORIG-GUID: 4aF6jT0sd5HoBTSt0Bl0NkX5HvtWMG7_ X-Proofpoint-GUID: 4aF6jT0sd5HoBTSt0Bl0NkX5HvtWMG7_ 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 mlxscore=0 phishscore=0 suspectscore=0 malwarescore=0 spamscore=0 adultscore=0 mlxlogscore=999 clxscore=1030 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2308100000 definitions=main-2409120139 Received-SPF: pass client-ip=17.58.63.184; envelope-from=summeremacs@summerstar.me; helo=st43p00im-ztbu10073601.me.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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:323565 Archived-At: --Apple-Mail=_75604091-64C1-4B40-BC87-CEEE6C7A9EDC Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On Sep 12, 2024, at 20:26, Philip Kaludercic = wrote: >=20 > Summer Emacs > writes: >=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. The goal of this project would be the following: >>=20 >> 1) A very visible (easy to see, and hard to miss) link at the top >> which says something like =E2=80=9CNew to Emacs? Click here!=E2=80=9D >> 2) A simple =E2=80=9Cone page=E2=80=9D info page with some general = information about >> Emacs and suggested setups. This would include: >=20 > Any reason for it being a "one page" (i.e. one section) page? Why use > Info, instead of a Help buffer? Good question: The =E2=80=9Cone page=E2=80=9D I=E2=80=99m 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 =E2=80=9Cout of the = box=E2=80=9D (I >> know this is contentious, please don=E2=80=99t bite my head off) >=20 > 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=E2=80=A6a quick = explanation >=20 > 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. >>=20 >> Now, a few things: >> 1) I=E2=80=99m not a dev. This is just my take from a non-dev = perspective. >> 2) I=E2=80=99ve heard there was work on a wizard setup a while back = but that >> it never went anywhere.=20 >=20 > 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. =E2=80=9CJust = RTFM=E2=80=9D isn=E2=80=99t the same anymore. Veronica just did a video = on how =E2=80=9CThe Manual=E2=80=9D has changed over the years: = https://www.youtube.com/watch?v=3D4lUiUQOvRHQ (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=E2=80=99m not = aiming to hold the hands of developers who are used to looking up = functions on the fly; I=E2=80=99m proposing we have a page with = sub-pages of easily understood material for non-developers and coders. I = also am not proposing that we =E2=80=9Cchange=E2=80=9D Emacs in any way = - I love Emacs the way it is. It=E2=80=99s just want an instantly = available newbie section. It=E2=80=99s not a huge ask, right? =3D) >=20 >> My suggestion is to use the info pages instead >> of a wizard, but to make a newbie =E2=80=9Chome base=E2=80=9D for new = users which >> won=E2=80=99t overwhelm them. I=E2=80=99ve 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=E2=80=99ve >> never written a tutorial before, so I=E2=80=99m going to need some = volunteers >> to help me with some of this stuff. >> 3) I don=E2=80=99t know what it takes to include such a thing into = Emacs >> proper. I don=E2=80=99t know how to patch things, or know what the = specifics >> are for submitting things in a proper way. Please don=E2=80=99t hold = that >> against me - I=E2=80=99m willing to learn. >=20 > 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=E2=80=99ve 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=E2=80=99= ll get to elisp when I have time. =3D) >=20 >> I wanted to write this email to put something concrete down rather >> than just say =E2=80=9CEmacs needs to be better for newbs=E2=80=9D = and not do anything >> about it. Somebody suggest that I actually do, so I=E2=80=99m going = to try. >>=20 >> I also don=E2=80=99t know if long emails are verboten here, so please = excuse >> the length of this email. I=E2=80=9Dm used to writing large business = projects >> and proposals where a few pages in length isn=E2=80=99t really much = of an >> issue. >=20 > This is certainly not the longest email I have seen here ^^ That=E2=80=99s good to know! Ty. =3D) >> The reason I=E2=80=99m doing this: >> I love Emacs, but I=E2=80=99m 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=E2=80=99t put off as much by the initial welcome screen., But I = know that >> many others might be. I=E2=80=99m not suggesting we change the = welcome screen >> because I know that=E2=80=99s an issue which causes fights and = division in the >> group - I=E2=80=99m 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. >>=20 >> 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. >>=20 >> Summer Emacs. >=20 > --=20 > Philip Kaludercic on siskin Summer Emacs. --Apple-Mail=_75604091-64C1-4B40-BC87-CEEE6C7A9EDC Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8
On Sep 12, = 2024, at 20:26, Philip Kaludercic <philipk@posteo.net> = wrote:

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 =E2=80=9CNew to Emacs? Click = here!=E2=80=9D
2) A simple =E2=80=9Cone page=E2=80=9D 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 =E2=80=9Cone page=E2=80=9D I=E2=80=99m 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 =E2=80=9C= out of the box=E2=80=9D (I
know this is contentious, please don=E2=80=99= 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=E2=80=A6a quick explanation

What is = EWS?

Emacs = Writing Studio. Just released.https://github.co= m/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=E2=80=99m not a dev. This is just my take from a = non-dev perspective.
2) I=E2=80=99ve 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. =E2=80=9CJust RTFM=E2=80=9D= isn=E2=80=99t the same anymore. Veronica just did a video on how =E2=80=9C= The Manual=E2=80=9D has changed over the years: https://www.youtube= .com/watch?v=3D4lUiUQOvRHQ (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=E2=80=99m not aiming to = hold the hands of developers who are used to looking up functions on the = fly; I=E2=80=99m proposing we have a page with sub-pages of easily = understood material for non-developers and coders. I also am not = proposing that we =E2=80=9Cchange=E2=80=9D Emacs in any way - I love = Emacs the way it is. It=E2=80=99s just want an instantly available = newbie section. It=E2=80=99s not a huge ask, right? = =3D)


           &= nbsp;           My = suggestion is to use the info pages instead
of a wizard, but to make = a newbie =E2=80=9Chome base=E2=80=9D for new users which
won=E2=80=99t = overwhelm them. I=E2=80=99ve 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=E2=80=99ve
never written a tutorial before, so I=E2=80=99m = going to need some volunteers
to help me with some of this = stuff.
3) I don=E2=80=99t know what it takes to include such a thing = into Emacs
proper. I don=E2=80=99t know how to patch things, or know = what the specifics
are for submitting things in a proper way. Please = don=E2=80=99t hold that
against me - I=E2=80=99m 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=E2=80=99v= e 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=E2=80=99ll = get to elisp when I have time. =3D)


I wanted to = write this email to put something concrete down rather
than just say = =E2=80=9CEmacs needs to be better for newbs=E2=80=9D and not do = anything
about it. Somebody suggest that I actually do, so I=E2=80=99m = going to try.

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

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

That=E2=80=99s good to = know! Ty. =3D)

The reason I=E2=80=99m doing this:
I love Emacs, but I=E2=80=99m= 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=E2=80=99t = put off as much by the initial welcome screen., But I know that
many = others might be. I=E2=80=99m not suggesting we change the welcome = screen
because I know that=E2=80=99s an issue which causes fights and = division in the
group - I=E2=80=99m 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.

= --Apple-Mail=_75604091-64C1-4B40-BC87-CEEE6C7A9EDC--