From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kevin Rodgers Newsgroups: gmane.emacs.devel Subject: Re: jargon translation up-front in doc (was: Menu suggestion) Date: Thu, 29 Apr 2004 09:44:11 -0600 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <409122CB.5030400@yahoo.com> References: <9003-Tue27Apr2004084357+0300-eliz@gnu.org> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1083254110 11421 80.91.224.253 (29 Apr 2004 15:55:10 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 29 Apr 2004 15:55:10 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Thu Apr 29 17:54:49 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 1BJDs9-00008w-00 for ; Thu, 29 Apr 2004 17:54:49 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BJDs8-0008E0-00 for ; Thu, 29 Apr 2004 17:54:48 +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 1BJDjf-0002w0-US for emacs-devel@quimby.gnus.org; Thu, 29 Apr 2004 11:46:03 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1BJDiy-0002o3-9s for emacs-devel@gnu.org; Thu, 29 Apr 2004 11:45:20 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1BJDiM-0002Zt-M0 for emacs-devel@gnu.org; Thu, 29 Apr 2004 11:45:15 -0400 Original-Received: from [80.91.224.249] (helo=main.gmane.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1BJDhT-0002MR-Lu for emacs-devel@gnu.org; Thu, 29 Apr 2004 11:43:47 -0400 Original-Received: from list by main.gmane.org with local (Exim 3.35 #1 (Debian)) id 1BJDhS-0007CJ-00 for ; Thu, 29 Apr 2004 17:43:47 +0200 Original-Received: from 170.207.51.80 ([170.207.51.80]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 29 Apr 2004 17:43:46 +0200 Original-Received: from ihs_4664 by 170.207.51.80 with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 29 Apr 2004 17:43:46 +0200 X-Injected-Via-Gmane: http://gmane.org/ Original-To: emacs-devel@gnu.org Original-Lines: 33 Original-X-Complaints-To: usenet@sea.gmane.org X-Gmane-NNTP-Posting-Host: 170.207.51.80 User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:0.9.4.1) Gecko/20020406 Netscape6/6.2.2 X-Accept-Language: en-us 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:22366 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:22366 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? -- Kevin Rodgers