From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.help Subject: RE: Using Emacs' help system Date: Sun, 10 Feb 2013 17:41:21 -0800 Message-ID: <8920FA7D30CB4A11827F992A7FF86156@us.oracle.com> References: <87obfr688e.fsf@dimension8.tehua.net> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1360546901 24951 80.91.229.3 (11 Feb 2013 01:41:41 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 11 Feb 2013 01:41:41 +0000 (UTC) To: "'Aidan Gauland'" , Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Mon Feb 11 02:42:02 2013 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1U4iPC-0000sr-7J for geh-help-gnu-emacs@m.gmane.org; Mon, 11 Feb 2013 02:42:02 +0100 Original-Received: from localhost ([::1]:56784 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U4iOt-0005Pp-2T for geh-help-gnu-emacs@m.gmane.org; Sun, 10 Feb 2013 20:41:43 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:59843) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U4iOn-0005Pk-Bz for help-gnu-emacs@gnu.org; Sun, 10 Feb 2013 20:41:38 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1U4iOk-0003Em-5T for help-gnu-emacs@gnu.org; Sun, 10 Feb 2013 20:41:37 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:48576) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U4iOj-0003Ec-Ul for help-gnu-emacs@gnu.org; Sun, 10 Feb 2013 20:41:34 -0500 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r1B1fV31003516 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 11 Feb 2013 01:41:32 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r1B1fUVa022453 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 11 Feb 2013 01:41:31 GMT Original-Received: from abhmt104.oracle.com (abhmt104.oracle.com [141.146.116.56]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r1B1fUT3029654; Sun, 10 Feb 2013 19:41:30 -0600 Original-Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 10 Feb 2013 17:41:30 -0800 X-Mailer: Microsoft Office Outlook 11 In-reply-to: <87obfr688e.fsf@dimension8.tehua.net> Thread-Index: Ac4H7kms9WnMbWbHSKm96oIe1zcxVQAA2oFw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:89055 Archived-At: > > I wanted to get the character count in a region. > > A quick Google search showed that I needed > > count-word-region`. My question is how could I have > > used the help system to get there? > > I think this is a case of obscure naming. Bad naming, I'd say. It wouldn't hurt to at least create alias commands with "characters" (or "chars") and "lines" in the names: `count-chars-region', `count-lines-region'. Oh, guess what? There is an alias `count-lines-region' (but none for chars). Why for lines? Not because someone thought it would be a good idea to create such an alias. No, the alias for lines is there only because `count-lines-region' was the original command (goes way back), and it's now been declared obsolete. As long as it is still supported it has the right to an alias. It also wouldn't hurt Emacs Lisp to have functions that did just those things, returning the count of chars and lines, respectively. `count-word-region' always returns the number of words. This is a false economy. FWIW, I've had a command `count-chars-in-region' for years (long before `count-words-region), which I use also in Lisp. And I've always had an alias for it: `region-length'. Why the alias? Again, discoverability - depends on how you are thinking about things. (We don't have a function named `count-elements-list' - we call the function `length'.) > That function doesn't mention in its docstring that it > returns a character count as well. The command name doesn't tell you that it counts characters, but its doc string does, actually: ,---- | count-words-region is an interactive compiled Lisp function in | `simple.el'. | | It is bound to M-=. | | (count-words-region START END &optional ARG) | | Count the number of words in the region. | If called interactively, print a message reporting the number of | lines, words, and characters in the region (whether or not the ^^^^^^^^^^^^^^ | region is active); with prefix ARG, report for the entire buffer | rather than the region. | | If called from Lisp, return the number of words between positions | START and END. `---- You might think that `C-h d character count' would find this command. But it does not, because "count" is only in the function name and "character" is only in the doc string. But even `C-h d character number' (the keyword order is not important) does not work - I'm not sure why. Someone will no doubt enlighten us. However, using this regexp does work: C-h d number\(.\| \)*char (That's a newline char after the |, inserted using `C-q C-j'.) Bottom lines: (a) This is not a great doc string, at least from the point of view of discoverability. (b) A command name should reflect the action of counting characters - e.g., an alias `count-chars-region'. This too might help with this kind of search: http://www.emacswiki.org/Icicles_-_A_Propos_d'Apropos#Documentation-AproposMulti -Commands