From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: "What's This?" in Describe submenu Date: Mon, 22 Aug 2005 23:23:35 -0500 (CDT) Message-ID: <200508230423.j7N4NZX14856@raven.dms.auburn.edu> References: <4308398B.60401@gmx.at> <200508230008.j7N081514425@raven.dms.auburn.edu> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1124771157 14426 80.91.229.2 (23 Aug 2005 04:25:57 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 23 Aug 2005 04:25:57 +0000 (UTC) Cc: rudalics@gmx.at, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Aug 23 06:25:44 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1E7QLz-0004do-HE for ged-emacs-devel@m.gmane.org; Tue, 23 Aug 2005 06:25:39 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1E7QPG-0005o8-PP for ged-emacs-devel@m.gmane.org; Tue, 23 Aug 2005 00:29:02 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1E7QOs-0005cG-EC for emacs-devel@gnu.org; Tue, 23 Aug 2005 00:28:39 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1E7QOe-0005Z7-Ou for emacs-devel@gnu.org; Tue, 23 Aug 2005 00:28:26 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1E7QOe-0005Yj-LY for emacs-devel@gnu.org; Tue, 23 Aug 2005 00:28:24 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.34) id 1E7QL3-000287-6c; Tue, 23 Aug 2005 00:24:41 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id j7N4Npqt028025; Mon, 22 Aug 2005 23:23:51 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id j7N4NZX14856; Mon, 22 Aug 2005 23:23:35 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: eliz@gnu.org In-reply-to: (message from Eli Zaretskii on Tue, 23 Aug 2005 06:47:29 +0300) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:42340 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:42340 Eli Zaretskii wrote: Cynicism aside, what you say is a general complaint about our doc strings, not specific to the menu item we are discussing. What I am saying is that the really useful commands for beginners are C-K and C-F, not C-k and C-f. The latter are often more for Elisp programmers, or at least for more advanced users (or a last resort if C-K or C-F do not find any docs in the manuals). In effect, you are saying that "Describe Key" is useless for newbies. In many cases, and much more consistently useful alternatives are available. While I agree that we should make the documentation to use smaller words, That is not the problem. The docstring tries to document the docstring for Elisp programmers and aside from the fact that it is missing an (easily added) comma: - If non-nil untranslated is a vector + If non-nil, untranslated is a vector it is not that difficult to understand _for Elisp programmers_. C-h C-F C-h C-k gives useful documentation for novices. Sincerely, Luc.