From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: Emacs Newbie Info Pages Date: Thu, 12 Sep 2024 19:17:51 +0000 Message-ID: <87seu44r6o.fsf@posteo.net> References: <87wmjg4tkq.fsf@posteo.net> <391666A2-D4BA-4DFE-9FF6-CAA48797EC97@summerstar.me> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="3053"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Summer Emacs Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Sep 12 21:18:34 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 1sopKr-0000gm-8f for ged-emacs-devel@m.gmane-mx.org; Thu, 12 Sep 2024 21:18:33 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sopKM-0001II-JT; Thu, 12 Sep 2024 15:18:02 -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 1sopKK-0001I3-Lp for emacs-devel@gnu.org; Thu, 12 Sep 2024 15:18:00 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sopKI-0006U8-1D for emacs-devel@gnu.org; Thu, 12 Sep 2024 15:18:00 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id BB7AC240028 for ; Thu, 12 Sep 2024 21:17:53 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1726168673; bh=sxPP0hQ0cKkVsV0nCzF9ja9qBhWXTC+gDE9DgZjaEjs=; h=From:To:Cc:Subject:Autocrypt:OpenPGP:Date:Message-ID:MIME-Version: Content-Type:Content-Transfer-Encoding:From; b=BpEJHKwcj/GMLB9+dItgGYMKh7pf0V3xUK1OvpXRg2EQDHheDaRKp+wOYgeH2UsIu vmIfRya8WUw467jWn0Telw2bv5it3jk06Qsrl5YQARTHyFopKnmj+7s9k/vPI0e13A XnKnIqeXOzmjrqY2zJBhjFDkAU5RILS61oasehVkPvPwO+RbRIo1W/VGp73rsHjnLP filKU8PngyTecVadwFBJAOtNnLWMYZEoENoVn6zLt+VdtUCcwR6ALQ4GZU3TugHo4u yLqqN5zPxIzFLGaTheduieoB2dqMW9FwCA8SqdPSDrzQVZkKN2XanrSDg8rCap5cMQ mKV22HsmMfGcQ== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4X4RzP0Mhxz9rxP; Thu, 12 Sep 2024 21:17:52 +0200 (CEST) In-Reply-To: <391666A2-D4BA-4DFE-9FF6-CAA48797EC97@summerstar.me> (Summer Emacs's message of "Thu, 12 Sep 2024 20:45:48 +0200") Autocrypt: addr=philipk@posteo.net; keydata= mDMEZBBQQhYJKwYBBAHaRw8BAQdAHJuofBrfqFh12uQu0Yi7mrl525F28eTmwUDflFNmdui0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiWBBMWCAA+FiEEDg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwMFCQHhM4AFCwkI BwIGFQoJCAsCBBYCAwECHgECF4AACgkQ8xYDWXahwulikAEA77hloUiSrXgFkUVJhlKBpLCHUjA0 mWZ9j9w5d08+jVwBAK6c4iGP7j+/PhbkxaEKa4V3MzIl7zJkcNNjHCXmvFcEuDgEZBBQQhIKKwYB BAGXVQEFAQEHQI5NLiLRjZy3OfSt1dhCmFyn+fN/QKELUYQetiaoe+MMAwEIB4h+BBgWCAAmFiEE Dg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwwFCQHhM4AACgkQ8xYDWXahwukm+wEA8cml4JpK NeAu65rg+auKrPOP6TP/4YWRCTIvuYDm0joBALw98AMz7/qMHvSCeU/hw9PL6u6R2EScxtpKnWof z4oM OpenPGP: id=philipk@posteo.net; url="https://keys.openpgp.org/vks/v1/by-email/philipk@posteo.net"; preference=signencrypt Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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, RCVD_IN_DNSWL_MED=-2.3, 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:323567 Archived-At: (Friendly reminder: Please don't forget to CC everyone when responding, otherwise some people might miss your response!) Summer Emacs writes: >> 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 info= rmation 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). 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 =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. 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=20 --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=20 [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=E2=80=A6a quick expl= anation >>=20 >> 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. >>>=20 >>> Now, a few things: >>> 1) I=E2=80=99m not a dev. This is just my take from a non-dev perspecti= ve. >>> 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 RTF= M=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) 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? >>=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 u= sers which >>> won=E2=80=99t overwhelm them. I=E2=80=99ve already written about 3 page= s 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 volu= nteers >>> 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 spec= ifics >>> are for submitting things in a proper way. Please don=E2=80=99t hold th= at >>> 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 pr= epare > 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) 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. >>=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 e= xcuse >>> the length of this email. I=E2=80=9Dm used to writing large business pr= ojects >>> 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 sl= eepless >>> 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 kn= ow 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. > --=20 Philip Kaludercic on siskin