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: Thu, 29 Apr 2004 10:37:44 -0700 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <409122CB.5030400@yahoo.com> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1083261489 31793 80.91.224.253 (29 Apr 2004 17:58:09 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 29 Apr 2004 17:58:09 +0000 (UTC) Cc: eliz@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Thu Apr 29 19:57:56 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 1BJFnI-0002a7-00 for ; Thu, 29 Apr 2004 19:57:56 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BJFnH-0001wQ-01 for ; Thu, 29 Apr 2004 19:57:55 +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 1BJFkO-0005n0-6J for emacs-devel@quimby.gnus.org; Thu, 29 Apr 2004 13:54:56 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BJFkA-0005mF-OE for emacs-devel@gnu.org; Thu, 29 Apr 2004 13:54:42 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BJFWm-0002wM-O4 for emacs-devel@gnu.org; Thu, 29 Apr 2004 13:41:23 -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 1BJFWm-0002vX-4H; Thu, 29 Apr 2004 13:40:52 -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 i3THelBS017346; Thu, 29 Apr 2004 10:40:48 -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 i3THbjon014218; Thu, 29 Apr 2004 10:38:15 -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 i3THbjCW006178; Thu, 29 Apr 2004 11:37:45 -0600 Original-Received: from dradamslap (dradams-lap.us.oracle.com [130.35.177.126]) by rgmgw2.us.oracle.com (Switch-3.1.4/Switch-3.1.0) with SMTP id i3THbisZ006166; Thu, 29 Apr 2004 11:37:45 -0600 Original-To: "Kevin Rodgers" , X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-reply-to: <409122CB.5030400@yahoo.com> Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1409 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:22372 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:22372 That might be good (though excessive hyperlinking can be obfuscating, so occurrences should *not* all become hyperlinks automatically). If we provided such hyperlinking, programmers should have a way to explicitly, selectively apply it (just as they can selectively expand command names in doc strings to provide key bindings: \\[foobar]). However, that does *not* address the main issue I raised. (Eli also missed it, so I must not be making myself clear.) Explaining our jargon is one thing. Come across "yank" somewhere, don't know what it means, click it, get the definition - great. What's missing is the set of common terms as user **entry points**. We should *mention* those terms, and then provide a bridge to our similar terms. Just defining our own terms doesn't provide this learning bridge. A user should be able to do `M-x command-apropos paste' and come up with the *few, common* commands that involve pasting. A user should be able to see "paste" prominently in the user interface. Today, "Paste" is available in the Edit menu - that's great. Let's also make it available in the first line of (a few) appropriate doc strings. (I just tried `M-x command-apropos paste' and came up with only dv-paste-to-temp: Load clipboard in buffer `TEMP' - gnuserv.) - 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 Kevin Rodgers Sent: Thursday, April 29, 2004 8:44 AM To: emacs-devel@gnu.org Subject: Re: jargon translation up-front in doc (was: Menu suggestion) Drew Adams wrote: > 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".) How about automatically highlighting and hyperlinking glossary terms in doc strings to the corresponding entry in the Glossary info node?