RE: Using Emacs' help system

[Drew Adams]

> > 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