From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: jargon translation up-front in doc (was: Menu suggestion) Date: Wed, 28 Apr 2004 18:48:15 -0700 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <9003-Tue27Apr2004084357+0300-eliz@gnu.org> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1083203538 32180 80.91.224.253 (29 Apr 2004 01:52:18 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 29 Apr 2004 01:52:18 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Thu Apr 29 03:52:04 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BJ0ia-0001vP-00 for ; Thu, 29 Apr 2004 03:52:04 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BJ0ia-00019u-00 for ; Thu, 29 Apr 2004 03:52:04 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1BJ0hA-0007AR-7z for emacs-devel@quimby.gnus.org; Wed, 28 Apr 2004 21:50:36 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BJ0g6-0006oB-Ia for emacs-devel@gnu.org; Wed, 28 Apr 2004 21:49:30 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BJ0fT-0006bS-BR for emacs-devel@gnu.org; Wed, 28 Apr 2004 21:49:22 -0400 Original-Received: from [141.146.126.231] (helo=agminet04.oracle.com) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.30) id 1BJ0ex-0006Tv-8s; Wed, 28 Apr 2004 21:48:19 -0400 Original-Received: from agminet04.oracle.com (localhost [127.0.0.1]) by agminet04.oracle.com (Switch-3.1.4/Switch-3.1.0) with ESMTP id i3T1mHZc010013; Wed, 28 Apr 2004 18:48:17 -0700 Original-Received: from rgmgw2.us.oracle.com (rgmgw2.us.oracle.com [138.1.191.11]) by agminet04.oracle.com (Switch-3.1.4/Switch-3.1.0) with ESMTP id i3T1mGXi009992; Wed, 28 Apr 2004 18:48:16 -0700 Original-Received: from rgmgw2.us.oracle.com (localhost [127.0.0.1]) by rgmgw2.us.oracle.com (Switch-3.1.4/Switch-3.1.0) with ESMTP id i3T1mFCi025488; Wed, 28 Apr 2004 19:48:15 -0600 Original-Received: from dradamslap (dhcp-amer-vpn-gw1-east-141-144-64-109.vpn.oracle.com [141.144.64.109]) by rgmgw2.us.oracle.com (Switch-3.1.4/Switch-3.1.0) with SMTP id i3T1mFns025475; Wed, 28 Apr 2004 19:48:15 -0600 Original-To: "Eli Zaretskii" , X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1409 In-Reply-To: <9003-Tue27Apr2004084357+0300-eliz@gnu.org> Importance: Normal X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.4 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:22327 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:22327 Two suggestions in the same spirit that was behind naming the Edit menu items "Cut", "Copy", and "Paste" (rather than something like "Kill", "Copy As Kill", and "Yank"). Suggestion #1: a doc table translating five Emacs-speak terms (restated) My point was not to *replace* anything in the tutorial or anything in the manual. I too assume that all Emacs terms are defined there before they are used. My point was this: 1) In the world outside Emacs (yes, Virginia...) many people are already familiar with similar (though not identical) concepts under very different names. 2) So, it can help them to learn Emacs - and to understand its doc - if we give them a simple, if inexact, translation table for these few terms (five terms, unless you see others) - *up front*, before any systematic explanation or tutorial of anything. Common Term Emacs Term ----------- ---------- selection region cut kill paste yank window frame shortcut key sequence If they are familiar with these common terms, then this table can help a lot; if not, they can ignore it. That's all. The usefulness of such a simple table is *not* achieved by any up-front reference to "go read the glossary". And it is not replaced by making sure that each new term is defined in the doc before it is used. And yes, there is no guarantee that a user will see such an up-front table. But it cannot hurt to add it, and it can help. Suggestion #2: Mention such common terms in doc strings, parenthetically, for a touchstone. Since some new users are likely to see `C-h k' help for commonly used keys before they read the doc or run through the tutorial, it wouldn't hurt to add the associated "common" term(s) somewhere in the doc strings of a **few** important, common commands - in parentheses or as added explanation. Example commands: `kill-region', `clipboard-kill-region', `yank', `clipboard-yank', `kill-ring-save', `clipboard-kill-ring-save'. This would also help with finding relevant commands using `command-apropos'. And it would help them learn the associated Emacs terminology that they will need in order to understand other concepts. Again, ignore this suggestion if the Emacs 21 doc strings for these commands already refer to "cut", "paste", and "copy" - I have only Emacs 20. The menubar command names "Cut", "Paste", and "Copy" are helpful to newbies, but the doc strings are not correspondingly clear (in Emacs 20, at least). It wouldn't take much to add a simple explanation that provides a bridge to familiar concepts (added text: <<>>): `kill-region' - "Kill between point and mark. <>" (The complete doc string in Emacs 20 is 14 lines long, without once using the word "cut", the word "paste", or the word "selected".) `clipboard-kill-ring-save' - "Copy region to kill ring, and save in the X clipboard. <>" `yank' - "Reinsert the last stretch of killed text. <>" (BTW, the doc string currently says nothing about *where* the text is inserted.) `kill-ring-save' is already an example of applying suggestion #2: Among six lines of arcane stuff about transient mark mode and mark deactivation, we do mention "cut" and "paste" - that's the kind of additional help I'm suggesting Emacs should offer. Yes, I realize that the Emacs functions do not map 1-1 to the common operations, and it can be misleading to suggest otherwise. Nonetheless, as long as the "real" explanation is present and precise, it can help if we add some perhaps imprecise but very familiar terminology in a few key places. I would further suggest that the *first* doc-string line be the perhaps-imprecise explanation using familiar terms (that is, reverse the order shown above). The rest of the doc-string can be as arcane as is needed to explain the concepts precisely. - Drew -----Original Message----- From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org [mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of Eli Zaretskii Sent: Monday, April 26, 2004 11:44 PM To: Drew Adams Cc: emacs-devel@gnu.org Subject: Re: jargon translation up-front in doc (was: Menu suggestion) > From: "Drew Adams" > Date: Mon, 26 Apr 2004 09:36:55 -0700 > > Proposal - Add a *brief* jargon translation near the beginning of the > tutorial and the Emacs manual, such as that at > http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbie, "Fundamental Concepts" > > "Emacs-Speak (Jargon)". I think the tutorial should explain each term before it uses it for the first time, rather than have a translation table. If this is not so, please point out the places that need to ve fixed. For the manual, we already have all the terms, including the 5 you mentioned, explained in the Glossary node. Perhaps all we need to do is add a reference to that node near the manual's beginning. I'm not sure how much it will help, since I don't think many people read the manual from its beginning, but it surely cannot hurt, I think.