From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: RE: (emacs) Intro [was: Making Emacs popular again with a video] Date: Thu, 28 May 2020 03:23:24 -0700 Message-ID: References: <779cc2b0-c546-2a80-afd3-79f10bda1b7e@yandex.ru> 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="74131"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Drew Adams To: "excalamus--- via Emacs development discussions." , excalamus@tutanota.com Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu May 28 12:23:59 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 1jeFhf-000JC0-7G for ged-emacs-devel@m.gmane-mx.org; Thu, 28 May 2020 12:23:59 +0200 Original-Received: from localhost ([::1]:59738 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jeFhe-00027z-7O for ged-emacs-devel@m.gmane-mx.org; Thu, 28 May 2020 06:23:58 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:45110) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jeFh9-0001PT-LN for emacs-devel@gnu.org; Thu, 28 May 2020 06:23:27 -0400 Original-Received: from mail-yb1-xb32.google.com ([2607:f8b0:4864:20::b32]:36168) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jeFh8-00038A-La for emacs-devel@gnu.org; Thu, 28 May 2020 06:23:27 -0400 Original-Received: by mail-yb1-xb32.google.com with SMTP id y18so5688759ybb.3 for ; Thu, 28 May 2020 03:23:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:in-reply-to:references:mime-version:date:message-id:subject:to :cc:content-transfer-encoding; bh=fOiDSpkoYopJrQG9Aw7Zy37U9OUosZjAI1C1gmuSwuQ=; b=hzZTZnUrEMwMWpbw3Vq55JauCiosNLPeuYdxYu5HsRPx2LpwxOI5o+wFLewWwKUvoV OaiP2H0X2wIFiASqWOHxWgWTXXJLFKnqt5mV4V6CiGtixZhvYjEVqYafYg6XDyajLiuv OuOrQT1MBA8a1PZ7CnQCLdSVzM7+00zu3nyWFGUlbNWLB5az87E0uvXbvv2n+ngvD2q6 EXHOmOBm0a04sV0EyM5qc1ua1CywralXSMvGPGOngYHGpl4oURwS5sUerKRR05Xiho4w pyLUQQZKS6lS5G+D8r8WRAfn+B0iMvAgYmOcWeHY1eSZcHcyc1D5IvFS8QEGAdPynnOi 8Y/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to:cc:content-transfer-encoding; bh=fOiDSpkoYopJrQG9Aw7Zy37U9OUosZjAI1C1gmuSwuQ=; b=XDn3QzzCx1lBhZpP6j33Mve96ZAwOdUvkxCUX81SQzKWPdtChle0eTukDyRvBPEJMZ cXFXa9U5vnAOI0kncwnBuDg+Fx9OFxrwoDA9GCHFqg90bm85CfO/ykel4v8DZ+pV6UFE nAS78rW3UyJ5gGmg8Re/49QzQ5svMB82amnrMqzZhI+CeFJUNl1ddAenBTJipkNLhtmy YujRnX3KT+ReQPn/JHuM68DRaSMlgDqodmPfLOeODe/PJ3pRpcUvgzQR+JR4u3MCyLID sfiQbdaJj5LggysSCu3su8HLWJoqS8uJNUgKaCu3PdacHYK4CosVj1dZ5OVN7VCTA93i F+0g== X-Gm-Message-State: AOAM530+zM03rGcQ7VwbRw7Y1/7vdDKThewTQkEi66BYt6kL148qWWdt cLEbNKgcQ/Jl2muOTuc3g7f8o0QPdozPN5jxH0hXsw== X-Google-Smtp-Source: ABdhPJwOhb3by4PL+2S9Mzs+3DKeft8gBAzpQxqsawAK4lyOArmqSCLGBPRd6LecEV61AsKDD8i01BBrRZmR9mleCK4= X-Received: by 2002:a25:4c04:: with SMTP id z4mr4104223yba.466.1590661404708; Thu, 28 May 2020 03:23:24 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Thu, 28 May 2020 03:23:24 -0700 In-Reply-To: Received-SPF: pass client-ip=2607:f8b0:4864:20::b32; envelope-from=stefankangas@gmail.com; helo=mail-yb1-xb32.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_PASS=-0.001, UNPARSEABLE_RELAY=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:251542 Archived-At: Hi, My day-job involves copy-editing among other things. I like this revision overall, but hope you find the below observations useful. 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. 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 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. >> designed for introspection and extensibility.=C2=A0 These qualities enab= le >> far more than basic word processing, as this manual describes. Scratch "as this manual describes", it is superfluous. >> "Introspection" means GNU Emacs has self-knowledge.=C2=A0 Every aspect o= f 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 sour= ce >> code itself!=C2=A0 GNU Emacs has everything conveniently in-house, at yo= ur I would avoid using an exclamation mark here. 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. >> fingertips.=C2=A0 See Help. >> >> "Extensibility" means that you can alter GNU Emacs itself.=C2=A0 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? >> most everything in-between.=C2=A0 See Customization.=C2=A0 Moreover, you= 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 writ= ten >> in Lisp.=C2=A0 See Emacs Lisp Intro(eintr) if you want to learn how to e= xtend >> GNU Emacs. >> >> Authors and researchers, as well as programmers, use GNU Emacs.=C2=A0 It= has Better: "Authors, researchers and programmers all use GNU Emacs." >> 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 be= cause >> 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." (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, "Wha= t > 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. > 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". > However, this implies structural, if not intention, changes to the > overall manual. What do you have in mind more exactly? Best regards, Stefan Kangas