RE: (emacs) Intro [was: Making Emacs popular again with a video]

[excalamus]

>> May 28, 2020, 03:08 by >> eliz@gnu.org>> :
>>
>> Are you aware of the 'i' command in Info, and using it?   Because its 
>> purpose is precisely to help in the situations like you describe.
>>
Yes and no.  Thank you for reminding me and for bringing this up.  I find I run 
into problems  similar to those Andreas points out.  

> May 28, 2020, 03:08 by > eliz@gnu.org> :
>
> I think at this time and place, there's only one Emacs.  What
> "non-GNU" Emacsen are there that still need to be kept in mind?
>
GNU Emacs definitely dominates now.  Yet, GNU Emacs is not the only Emacs.  I'm 
not sure how to account for that when revising the manual.  

For instance, the first line of the current version is nonsense if GNU Emacs 
and Emacs are conflated:

> You are reading about GNU Emacs, the GNU incarnation of the advanced, 
> self-documenting, 
> customizable, extensible editor Emacs.

The node link description for the intro is "An introduction to Emacs concepts." 
 I took that to mean Emacsen, as that's primarily what (emacs) Intro describes. 
 Is it describing something else?  If it *is* describing Emacsen and we don't 
want it to be, what direction should it go?

Other thoughts:

- Strictly speaking GNU Emacs and Emacs are distinct.  What recommendations do 
you have for navigating the distinction?  Or should we *not* make a 
distinction?  Maybe I'm just being pedantic.
- Part of understanding GNU Emacs as a program is understanding its history.  
It's easier for me to comprehend aspects of Emacs (e.g. window/frame) when I 
realize it's been in existence longer than I have.  Maybe we should gloss over 
the distinction in the manual text and include a separate history node?   There 
are places, like (emacs) User Input, that reference "historical reasons" that 
might benefit from that.
- Terminology, like "Emacsen", exists within the community (EmacsWiki, etc.) 
which is confusing if you conflate GNU Emacs with Emacs.  I was certainly 
confused by this.  Maybe add such terminology to the glossary?
- Other Emacs are referenced within GNU Emacs's code-base.  Running grep on my 
Emacs install turns up 281 matches for "xemacs".  I doubt that's going to trip 
many people up, but who knows.


> May 28, 2020, 06:23 by > stefankangas@gmail.com> :
>
> Hi,
>
> My day-job involves copy-editing among other things.  I like this
> revision overall, but hope you find the below observations useful.
>
Absolutely!  I'm so stinkin' excited to be working with you (all) on this.  
Thank you for taking the time to share your perspective and experience!

> First, it doesn't push the point that this is an editor for "power
> users".  In my opinion, we should emphasize that point, as others have
> suggested.
>
I'm not sure how to do this.  How do you define a power user?

Other discussions make it seem like a focus on power users is a focus on 
features.  I opted to avoid that here.  A person will have already been sold on 
trying Emacs, likely based on features, well in advance to reading the manual.  
Focusing on features also opens the impossible question of "Which features 
should I highlight?"  I tried to provide context instead.  


> excalamus--- via "Emacs development discussions." <emacs-devel@gnu.org>
> writes:
>
>> Updated the proposed intro based on everyone's excellent feedback!
>>
>>> (nil)Top
>>>
>>> Welcome to the Exciting World of GNU Emacs!
>>> *******************************************
>>>
>>> GNU Emacs is born of two ideas, the GNU project and Emacs editors.  The
>>>
>
> "Emacs editors" here is confusing.  I'm not sure how to reformulate it,
> but see the below point.
>
>>> goal of the GNU project is to provide a complete, free software system.
>>> This means GNU Emacs respects you. It can adapt to how you work, not the
>>> other way around![1] An "Emacs" is a command oriented text editor
>>>
>
> Better: "Emacs is a command oriented text editor".  I understand what
> you're going for (there are other Emacs editors) but frankly it's not
> really a key point in an introduction and it is not easy understand this
> subtle point for readers.
>
Yeah, I grappled quite a bit with explaining what an Emacs is.  It's awkward.   
I think my comments to Eli above cover the main obstacles.

>>> "Introspection" means GNU Emacs has self-knowledge.  Every aspect of the
>>>
>
> I'm not sure about replacing "self-documenting" with "introspection",
> but whatever word we use I think it reads better if it starts
> "Introspection means that every aspect of the system...".
>
>>> system is documented and accessible.  Each level of inquiry has
>>> tutorials, guides, and references.  It can answer questions like, "What
>>> commands might help me?", "What does this do?", and, "How does this
>>> work?"  The documentation extends from general concepts to the source
>>> code itself!  GNU Emacs has everything conveniently in-house, at your
>>>
I'm beginning to doubt using "introspection", too.  RMS gives a good 
description of "self-documenting" on page 18 of "EMACS: The Extensible, 
Customizable, Self-Documenting Display Editor" 
(https://dspace.mit.edu/handle/1721.1/5736) 
<https://dspace.mit.edu/handle/1721.1/5736>. I tried to reuse the ideas.  The 
term "self-documenting" is undoubtedly correct, especially in the technical 
"search the dispatch table" sense.  Yet I find it doesn't encompass, at least 
immediately, the other aspects of the documentation: tutorials, references, and 
the source code, as well as ease of navigation. I feel introspection  gets at 
those more easily at the expense of being less precise.  Maybe "self-knowledge" 
and the line about the source code is enough?

> I would also scratch the word "in-house".  Perhaps add something that
> you don't need to fire up a web browser to read documentation, but can
> do it directly in Emacs itself.
>
Interesting.  I was going for brevity and trying to emphasize the ease of 
navigating the Emacs documentation.  I see your point.  Precise is probably 
better than general.   Actually, (navigates to Gutenberg), that's Strunk's Rule 
12: Use definite, specific, concrete language.

>>> fingertips.  See Help.
>>>
>>> "Extensibility" means that you can alter GNU Emacs itself.  You can
>>> customize the environment, from keyboard shortcuts to color themes, and
>>>
>
> "Color themes" is mostly an assumed feature in text editors and not
> terribly exciting.  Could we find a better example?
>
I wish... It's the riddle of what features to mention.  I don't have an answer 
for it.  I went with themes because even though it's common, people love 
messing with them.  At least it's beloved if not exciting.  Suggestions?

>>> most everything in-between.  See Customization.  Moreover, you can
>>> create and apply new commands in real-time. These can be packaged and
>>> shared with the diverse Emacs community.  Most of GNU Emacs is written
>>> in Lisp.  See Emacs Lisp Intro(eintr) if you want to learn how to extend
>>> GNU Emacs.
>>>
>>> Authors and researchers, as well as programmers, use GNU Emacs.  It has
>>>
>
> Better: "Authors, researchers and programmers all use GNU Emacs."
>
Agreed.

>>> seen active development for more than 40 years and includes innumerable
>>> features; it is a heritage as much as a tool.  We love GNU Emacs because
>>> we find its editing environment a rewarding experience like no other.
>>> We hope you'll feel that way, too.
>>>
>
> This paragraph is excellent.  Possibly you could try something like:
>
> "We love GNU Emacs because we find its editing environment a rewarding
> experience like no other.  It can adapt to your needs and grows with
> you.  We hope you'll love using it, too."
>
Thank you! I worked hard to come up with a variant to Karl's (?) "no other 
editing environment rewards sustained user investment quite like it" that 
didn't imply a steep learning curve*.  I hope this strikes the right balance.  
I like your suggestion, too, of moving the adapt+grow from P1 to here.  

*I am a SLC denier.

> (Just a rough draft, but something along those lines maybe.)
>
>> First, I think it oversells the accessibility of the documentation.
>> The Emacs documentation is extensive and well written.  However, I
>> find it quite difficult to navigate to a concept if that thing isn't a
>> function or variable.  I have been a beginner and asked myself, "What
>> is a cons cell?".  I found then, as I often still do, that leaving
>> Emacs (to use a web browser) yields results fast enough to not use
>> Emacs itself.  Ironically, I most often wind up at the gnu.org html
>> documentation.
>>
>
> The problem is not necessarily with your text.  It could just be that we
> should should identify the problematic areas and improve our
> documentation, the tutorial, etc.
>
Agreed.  I would like to talk about C-h discoverability and navigation when I 
have time.  I think there are taters there.

>> Second, the menu description is "Intro::An introduction to Emacs
>> concepts" which is no longer true in this version.
>>
>
> I propose to rename it to "An introduction to GNU Emacs".
>
Agreed.

>> However, this implies structural, if not intention, changes to the
>> overall manual.
>>
>
> What do you have in mind more exactly?
>
I mentioned some in my reply to Eli above.  Basically, I think "An Introduction 
to Emacs[en]" is addressed differently than "An Introduction to GNU Emacs".  
The intro sets the user up for what's to come.  Part of me wants to say the 
manual should guide end users to being hackers (power users?).  I have a hard 
time separating hackability from the other features listed.  I'm probably 
losing sight of the intent/purpose of the manual/introduction.