Re: Emacs Newbie Info Pages

[Philip Kaludercic <philipk@posteo.net>]

(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