From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: excalamus--- via "Emacs development discussions." Newsgroups: gmane.emacs.devel Subject: RE: (emacs) Intro [was: Making Emacs popular again with a video] Date: Fri, 29 May 2020 04:39:03 +0200 (CEST) Message-ID: References: <779cc2b0-c546-2a80-afd3-79f10bda1b7e@yandex.ru> Reply-To: excalamus@tutanota.com Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="2519"; mail-complaints-to="usenet@ciao.gmane.io" Cc: "excalamus--- via Emacs development discussions." , Drew Adams To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri May 29 04:39:48 2020 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 1jeUw0-0000WC-K4 for ged-emacs-devel@m.gmane-mx.org; Fri, 29 May 2020 04:39:48 +0200 Original-Received: from localhost ([::1]:60980 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jeUvz-0008Fq-9h for ged-emacs-devel@m.gmane-mx.org; Thu, 28 May 2020 22:39:47 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33014) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jeUvP-0007oH-8g for emacs-devel@gnu.org; Thu, 28 May 2020 22:39:11 -0400 Original-Received: from w1.tutanota.de ([81.3.6.162]:55760) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jeUvM-00062e-FU for emacs-devel@gnu.org; Thu, 28 May 2020 22:39:10 -0400 Original-Received: from w3.tutanota.de (unknown [192.168.1.164]) by w1.tutanota.de (Postfix) with ESMTP id 5B5DBFA03BB; Fri, 29 May 2020 02:39:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1590719943; s=s1; d=tutanota.com; h=From:From:To:To:Subject:Subject:Content-Description:Content-ID:Content-Type:Content-Type:Content-Transfer-Encoding:Content-Transfer-Encoding:Cc:Cc:Date:Date:In-Reply-To:In-Reply-To:MIME-Version:MIME-Version:Message-ID:Message-ID:Reply-To:References:References:Sender; bh=8m7mjJdR1a0ey8QXJAQ46uvu7a/imjpmKrMXdSTby7Y=; b=P/HCwdbImVseGorDxAiwWGlqRaOaSnNX6WG60qxbp4Y9XyQ1O8fd3QbD4h5pMMlf J3itn2Ubhn3R+0vYDjeKobiVC4WeuAPxdhR/GZDwHIjUDRcqH47nJ3zxQfdgiQiwqR+ 8wwKauUQwueZOZC+Cj3w7QNxUpieyvRkIGZ55oUpJ46gPmfsiUql+Pk5wFxng5DXvBO atzS1TAHrPURlfZAeEiQW+Kl8nVgKovkdHpj48MRQjawJmoalDhXmXyvbbMSitO6e4R 3NVSbsUrBDwq5BSToXZL3WnwvphG9q/k21Jbo2yFczhs8okpwCGUv8yDA2dfg4fI/d0 fniers8qaw== In-Reply-To: Received-SPF: pass client-ip=81.3.6.162; envelope-from=excalamus@tutanota.com; helo=w1.tutanota.de X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/28 22:39:03 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] 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, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=_AUTOLEARN X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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" Xref: news.gmane.io gmane.emacs.devel:251596 Archived-At: >> May 28, 2020, 03:08 by >> eliz@gnu.org>> : >> >> Are you aware of the 'i' command in Info, and using it?=C2=A0 Because i= ts purpose is precisely to help in the situations like you describe. >> Yes and no.=C2=A0 Thank you for reminding me and for bringing this up.=C2= =A0 I find I run into problems similar to those Andreas points out.=C2=A0= =20 > 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.=C2=A0 Yet, GNU Emacs is not the only Em= acs. =C2=A0I'm not sure how to account for that when revising the manual. = =C2=A0 For instance, the first line of the current version is nonsense if GNU Emac= s and Emacs are conflated: > You are reading about GNU Emacs, the GNU incarnation of the advanced, sel= f-documenting,=20 > customizable, extensible editor Emacs. The node link description for the intro is "An introduction to Emacs concep= ts."=C2=A0 I took that to mean Emacsen, as that's primarily what (emacs) In= tro describes.=C2=A0 Is it describing something else?=C2=A0 If it *is* desc= ribing Emacsen and we don't want it to be, what direction should it go? Other thoughts: - Strictly speaking GNU Emacs and Emacs are distinct.=C2=A0 What recommenda= tions do you have for navigating the distinction?=C2=A0 Or should we *not* = make a distinction?=C2=A0 Maybe I'm just being pedantic. - Part of understanding GNU Emacs as a program is understanding its history= .=C2=A0 It's easier for me to comprehend aspects of Emacs (e.g. window/fram= e) when I realize it's been in existence longer than I have.=C2=A0 Maybe we= should gloss over the distinction in the manual text and include a separat= e history node?=C2=A0=C2=A0 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.=C2=A0 I was cert= ainly confused by this.=C2=A0 Maybe add such terminology to the glossary? - Other Emacs are referenced within GNU Emacs's code-base.=C2=A0 Running gr= ep on my Emacs install turns up 281 matches for "xemacs".=C2=A0 I doubt tha= t'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!=C2=A0 I'm so stinkin' excited to be working with you (all) on t= his.=C2=A0 Thank you for taking the time to share your perspective and expe= rience! > 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. =C2=A0How do you define a power user? Other discussions make it seem like a focus on power users is a focus on fe= atures.=C2=A0 I opted to avoid that here.=C2=A0 A person will have already = been sold on trying Emacs, likely based on features, well in advance to rea= ding the manual.=C2=A0 Focusing on features also opens the impossible quest= ion of "Which features should I highlight?"=C2=A0 I tried to provide contex= t instead.=C2=A0=20 > excalamus--- via "Emacs development discussions." > 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.=C2= =A0 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 th= e >>> 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.=C2=A0 It's a= wkward.=C2=A0=C2=A0 I think my comments to Eli above cover the main obstacl= es. >>> "Introspection" means GNU Emacs has self-knowledge.=C2=A0 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.=C2=A0 Each level of inquiry has >>> tutorials, guides, and references.=C2=A0 It can answer questions like, = "What >>> commands might help me?", "What does this do?", and, "How does this >>> work?"=C2=A0 The documentation extends from general concepts to the sou= rce >>> code itself!=C2=A0 GNU Emacs has everything conveniently in-house, at y= our >>> I'm beginning to doubt using "introspection", too.=C2=A0 RMS gives a good d= escription of "self-documenting" on page 18 of "EMACS: The Extensible, Cust= omizable, Self-Documenting Display Editor" (https://dspace.mit.edu/handle/1= 721.1/5736) . I tried to reuse t= he ideas.=C2=A0 The term "self-documenting" is undoubtedly correct, especia= lly in the technical "search the dispatch table" sense.=C2=A0 Yet I find it= doesn't encompass, at least immediately, the other aspects of the document= ation: tutorials, references, and the source code, as well as ease of navig= ation. I feel introspection gets at those more easily at the expense of be= ing less precise.=C2=A0 Maybe "self-knowledge" and the line about the sourc= e 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.=C2=A0 I was going for brevity and trying to emphasize the ease= of navigating the Emacs documentation.=C2=A0 I see your point.=C2=A0 Preci= se is probably better than general.=C2=A0=C2=A0 Actually, (navigates to Gut= enberg), that's Strunk's Rule 12: Use definite, specific, concrete language= . >>> fingertips.=C2=A0 See Help. >>> >>> "Extensibility" means that you can alter GNU Emacs itself.=C2=A0 You ca= n >>> 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.=C2=A0 I don't have a= n answer for it.=C2=A0 I went with themes because even though it's common, = people love messing with them.=C2=A0 At least it's beloved if not exciting.= =C2=A0 Suggestions? >>> most everything in-between.=C2=A0 See Customization.=C2=A0 Moreover, yo= u can >>> create and apply new commands in real-time. These can be packaged and >>> shared with the diverse Emacs community.=C2=A0 Most of GNU Emacs is wri= tten >>> in Lisp.=C2=A0 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.=C2=A0 I= t 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.=C2=A0 We love GNU Emacs b= ecause >>> 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 d= idn't imply a steep learning curve*.=C2=A0 I hope this strikes the right ba= lance.=C2=A0 I like your suggestion, too, of moving the adapt+grow from P1 = to here.=C2=A0=20 *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.=C2=A0 However, I >> find it quite difficult to navigate to a concept if that thing isn't a >> function or variable.=C2=A0 I have been a beginner and asked myself, "Wh= at >> is a cons cell?".=C2=A0 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.=C2=A0 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.=C2=A0 I would like to talk about C-h discoverability and navigation= when I have time.=C2=A0 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.=C2=A0 Basically, I think "An Int= roduction to Emacs[en]" is addressed differently than "An Introduction to G= NU Emacs".=C2=A0 The intro sets the user up for what's to come.=C2=A0 Part = of me wants to say the manual should guide end users to being hackers (powe= r users?).=C2=A0 I have a hard time separating hackability from the other f= eatures listed.=C2=A0 I'm probably losing sight of the intent/purpose of th= e manual/introduction.